API Resources¶

Aliases¶

class Aliases(session_kwargs, client, return_type='civis')¶

Methods

`delete`(self, id)	Delete an alias
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get an Alias
`get_object_type`(self, object_type, alias)	Get details about an alias within an FCO type
`list`(self, \*[, object_type, limit, …])	List Aliases
`list_shares`(self, id)	List users and groups permissioned on this object
`patch`(self, id, \*[, object_id, …])	Update some attributes of this Alias
`post`(self, object_id, object_type, alias, \*)	Create an Alias
`put`(self, id, object_id, object_type, alias, \*)	Replace all attributes of this Alias
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete(self, id)¶

Delete an alias

Parameters:	id : integer The id of the Alias object.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Get an Alias

Parameters:

id : integer

Returns:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

get_object_type(self, object_type, alias)¶

Get details about an alias within an FCO type

Parameters:

object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object

Returns:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

list(self, *, object_type='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Aliases

Parameters:

object_type : string, optional: Filter results by object type. Pass multiple object types with a comma- separatedlist. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
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 id. Must be one of: id, object_type.
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 the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, id, *, object_id='DEFAULT', object_type='DEFAULT', alias='DEFAULT', display_name='DEFAULT')¶

Update some attributes of this Alias

Parameters:

id : integer: The id of the Alias object.
object_id : integer, optional: The id of the object
object_type : string, optional: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string, optional: The alias of the object
display_name : string, optional: The display name of the Alias object. Defaults to object name if not provided.

Returns:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

post(self, object_id, object_type, alias, *, display_name='DEFAULT')¶

Create an Alias

Parameters:

object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
display_name : string, optional: The display name of the Alias object. Defaults to object name if not provided.

Returns:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

put(self, id, object_id, object_type, alias, *, display_name='DEFAULT')¶

Replace all attributes of this Alias

Parameters:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
display_name : string, optional: The display name of the Alias object. Defaults to object name if not provided.

Returns:

id : integer: The id of the Alias object.
object_id : integer: The id of the object
object_type : string: The type of the object. Valid types include: model, cass_ncoa, container_script, gdoc_export, geocode, media_optimizer, python_script, r_script, salesforce_export, javascript_script, sql_script, project, notebook, workflow, template_script, template_report, service, report, tableau and service_report.
alias : string: The alias of the object
user_id : integer: The id of the user who created the alias
display_name : string: The display name of the Alias object. Defaults to object name if not provided.

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Announcements¶

class Announcements(session_kwargs, client, return_type='civis')¶

Methods

list(self, \*[, limit, page_num, order, …]) List announcements

list(self, *, 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

Clusters¶

class Clusters(session_kwargs, client, return_type='civis')¶

Methods

`delete_kubernetes_partitions`(self, id, …)	Delete a Cluster Partition
`get_kubernetes`(self, id, \*[, …])	Describe a Kubernetes Cluster
`get_kubernetes_instance_configs`(self, …[, …])	Describe an Instance Config
`get_kubernetes_partitions`(self, id, …[, …])	Describe a Cluster Partition
`list_kubernetes`(self, \*[, …])	List Kubernetes Clusters
`list_kubernetes_deployment_stats`(self, id)	Get stats about deployments associated with a Kubernetes Cluster
`list_kubernetes_deployments`(self, id, \*[, …])	List the deployments associated with a Kubernetes Cluster
`list_kubernetes_instance_configs_historical_graphs`(…)	Get graphs of historical resource usage in an Instance Config
`list_kubernetes_instance_configs_user_statistics`(…)	Get statistics about the current users of an Instance Config
`list_kubernetes_partitions`(self, id, \*[, …])	List Cluster Partitions for given cluster
`patch_kubernetes`(self, id, \*[, is_nat_enabled])	Update a Kubernetes Cluster
`patch_kubernetes_partitions`(self, id, …[, …])	Update a Cluster Partition
`post_kubernetes`(self, \*[, organization_id, …])	Create a Kubernetes Cluster
`post_kubernetes_partitions`(self, id, …)	Create a Cluster Partition for given cluster

delete_kubernetes_partitions(self, id, cluster_partition_id)¶

Delete a Cluster Partition

Parameters:	id : integer The ID of the cluster which this partition belongs to. cluster_partition_id : integer The ID of this cluster partition.
Returns:	None Response code 204: success

get_kubernetes(self, id, *, include_usage_stats='DEFAULT')¶

Describe a Kubernetes Cluster

Parameters:

id : integer
include_usage_stats : boolean, optional: When true, usage stats are returned in instance config objects. Defaults to false.

Returns:

id : integer

The ID of this cluster.

organization_id : string

The id of this cluster’s organization.

organization_name : string

The name of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

custom_partitions : boolean

Whether this cluster has a custom partition configuration.

cluster_partitions : list::

List of cluster partitions associated with this cluster. - cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.
labels : list

Labels associated with this partition.
instance_configs : list::
The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.
- instance_type : string
  
  An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
- min_instances : integer
  
  The minimum number of instances of that type in this cluster.
- max_instances : integer
  
  The maximum number of instances of that type in this cluster.
- instance_max_memory : integer
  
  The amount of memory (RAM) available to a single instance of that type in megabytes.
- instance_max_cpu : integer
  
  The number of processor shares available to a single instance of that type in millicores.
- instance_max_disk : integer
  
  The amount of disk available to a single instance of that type in gigabytes.
- usage_stats : dict::
  
  pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
  
  pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
  
  running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
  
  running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
  
  pending_deployments : integer
  
  The number of pending deployments in this instance config.
  
  running_deployments : integer
  
  The number of running deployments in this instance config.
default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

is_nat_enabled : boolean

Whether this cluster needs a NAT gateway or not.

hours : number/float

The number of hours used this month for this cluster.

get_kubernetes_instance_configs(self, instance_config_id, *, include_usage_stats='DEFAULT')¶

Describe an Instance Config

Parameters:

instance_config_id : integer: The ID of this instance config.
include_usage_stats : boolean, optional: When true, usage stats are returned in instance config objects. Defaults to false.

Returns:

instance_config_id : integer

The ID of this InstanceConfig.

instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.

min_instances : integer

The minimum number of instances of that type in this cluster.

max_instances : integer

The maximum number of instances of that type in this cluster.

instance_max_memory : integer

The amount of memory (RAM) available to a single instance of that type in megabytes.

instance_max_cpu : integer

The number of processor shares available to a single instance of that type in millicores.

instance_max_disk : integer

The amount of disk available to a single instance of that type in gigabytes.

usage_stats : dict::

pending_memory_requested : integer

The sum of memory requests (in MB) for pending deployments in this instance config.
pending_cpu_requested : integer

The sum of cpu requests (in millicores) for pending deployments in this instance config.
running_memory_requested : integer

The sum of memory requests (in MB) for running deployments in this instance config.
running_cpu_requested : integer

The sum of cpu requests (in millicores) for running deployments in this instance config.
pending_deployments : integer

The number of pending deployments in this instance config.
running_deployments : integer

The number of running deployments in this instance config.

cluster_partition_id : integer

The ID of this InstanceConfig’s cluster partition

cluster_partition_name : string

The name of this InstanceConfig’s cluster partition

get_kubernetes_partitions(self, id, cluster_partition_id, *, include_usage_stats='DEFAULT')¶

Describe a Cluster Partition

Parameters:

id : integer: The ID of the cluster which this partition belongs to.
cluster_partition_id : integer: The ID of this cluster partition.
include_usage_stats : boolean, optional: When true, usage stats are returned in instance config objects. Defaults to false.

Returns:

cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.

labels : list

Labels associated with this partition.

instance_configs : list::

The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.

instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.
instance_max_memory : integer

The amount of memory (RAM) available to a single instance of that type in megabytes.
instance_max_cpu : integer

The number of processor shares available to a single instance of that type in millicores.
instance_max_disk : integer

The amount of disk available to a single instance of that type in gigabytes.
usage_stats : dict::
- pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
- pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
- running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
- running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
- pending_deployments : integer
  
  The number of pending deployments in this instance config.
- running_deployments : integer
  
  The number of running deployments in this instance config.

default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

list_kubernetes(self, *, organization_slug='DEFAULT', raw_cluster_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.
raw_cluster_slug : string, optional: The slug of this cluster’s raw configuration.
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.

organization_id : string

The id of this cluster’s organization.

organization_name : string

The name of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

custom_partitions : boolean

Whether this cluster has a custom partition configuration.

cluster_partitions : list::

List of cluster partitions associated with this cluster. - cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.
labels : list

Labels associated with this partition.
instance_configs : list::
The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.
- instance_type : string
  
  An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
- min_instances : integer
  
  The minimum number of instances of that type in this cluster.
- max_instances : integer
  
  The maximum number of instances of that type in this cluster.
- instance_max_memory : integer
  
  The amount of memory (RAM) available to a single instance of that type in megabytes.
- instance_max_cpu : integer
  
  The number of processor shares available to a single instance of that type in millicores.
- instance_max_disk : integer
  
  The amount of disk available to a single instance of that type in gigabytes.
- usage_stats : dict::
  
  pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
  
  pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
  
  running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
  
  running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
  
  pending_deployments : integer
  
  The number of pending deployments in this instance config.
  
  running_deployments : integer
  
  The number of running deployments in this instance config.
default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

is_nat_enabled : boolean

Whether this cluster needs a NAT gateway or not.

list_kubernetes_deployment_stats(self, id)¶

Get stats about deployments associated with a Kubernetes Cluster

Parameters:	id : integer The ID of this cluster.
Returns:	base_type : string The base type of this deployment state : string State of the deployment count : integer Number of deployments of base type and state total_cpu : integer Total amount of CPU in millicores for deployments of base type and state total_memory : integer Total amount of Memory in megabytes for deployments of base type and state

list_kubernetes_deployments(self, id, *, base_type='DEFAULT', state='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List the deployments associated with a Kubernetes Cluster

Parameters:

id : integer: The id of the cluster.
base_type : string, optional: If specified, return deployments of these base types. It accepts a comma- separated list, possible values are ‘Notebook’, ‘Service’, ‘Run’.
state : string, optional: If specified, return deployments in these states. It accepts a comma- separated list, possible values are pending, running, terminated, sleeping
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.
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 deployment.

name : string

The name of the deployment.

base_id : integer

The id of the base object associated with the deployment.

base_type : string

The base type of this deployment.

state : string

The state of the deployment.

cpu : integer

The CPU in millicores required by the deployment.

memory : integer

The memory in MB required by the deployment.

disk_space : integer

The disk space in GB required by the deployment.

instance_type : string

The EC2 instance type requested for the deployment.

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.

created_at : string/time

updated_at : string/time

list_kubernetes_instance_configs_historical_graphs(self, instance_config_id, *, timeframe='DEFAULT')¶

Get graphs of historical resource usage in an Instance Config

Parameters:	instance_config_id : integer The ID of this instance config. timeframe : string, optional The span of time that the graphs cover. Must be one of 1_day, 1_week.
Returns:	cpu_graph_url : string URL for the graph of historical CPU usage in this instance config. mem_graph_url : string URL for the graph of historical memory usage in this instance config.

list_kubernetes_instance_configs_user_statistics(self, instance_config_id, *, order='DEFAULT', order_dir='DEFAULT')¶

Get statistics about the current users of an Instance Config

Parameters:

instance_config_id : integer: The ID of this instance config.
order : string, optional: The field on which to order the result set. Defaults to running_deployments. Must be one of pending_memory_requested, pending_cpu_requested, running_memory_requested, running_cpu_requested, pending_deployments, running_deployments.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending). Defaults to desc.

Returns:

user_id : string: The owning user’s ID
user_name : string: The owning user’s name
pending_deployments : integer: The number of deployments belonging to the owning user in “pending” state
pending_memory_requested : integer: The sum of memory requests (in MB) for deployments belonging to the owning user in “pending” state
pending_cpu_requested : integer: The sum of CPU requests (in millicores) for deployments belonging to the owning user in “pending” state
running_deployments : integer: The number of deployments belonging to the owning user in “running” state
running_memory_requested : integer: The sum of memory requests (in MB) for deployments belonging to the owning user in “running” state
running_cpu_requested : integer: The sum of CPU requests (in millicores) for deployments belonging to the owning user in “running” state

list_kubernetes_partitions(self, id, *, include_usage_stats='DEFAULT')¶

List Cluster Partitions for given cluster

Parameters:

id : integer
include_usage_stats : boolean, optional: When true, usage stats are returned in instance config objects. Defaults to false.

Returns:

cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.

labels : list

Labels associated with this partition.

instance_configs : list::

The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.

instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.
instance_max_memory : integer

The amount of memory (RAM) available to a single instance of that type in megabytes.
instance_max_cpu : integer

The number of processor shares available to a single instance of that type in millicores.
instance_max_disk : integer

The amount of disk available to a single instance of that type in gigabytes.
usage_stats : dict::
- pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
- pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
- running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
- running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
- pending_deployments : integer
  
  The number of pending deployments in this instance config.
- running_deployments : integer
  
  The number of running deployments in this instance config.

default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

patch_kubernetes(self, id, *, is_nat_enabled='DEFAULT')¶

Update a Kubernetes Cluster

Parameters:

id : integer: The ID of this cluster.
is_nat_enabled : boolean, optional: Whether this cluster needs a NAT gateway or not.

Returns:

id : integer

The ID of this cluster.

organization_id : string

The id of this cluster’s organization.

organization_name : string

The name of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

custom_partitions : boolean

Whether this cluster has a custom partition configuration.

cluster_partitions : list::

List of cluster partitions associated with this cluster. - cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.
labels : list

Labels associated with this partition.
instance_configs : list::
The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.
- instance_type : string
  
  An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
- min_instances : integer
  
  The minimum number of instances of that type in this cluster.
- max_instances : integer
  
  The maximum number of instances of that type in this cluster.
- instance_max_memory : integer
  
  The amount of memory (RAM) available to a single instance of that type in megabytes.
- instance_max_cpu : integer
  
  The number of processor shares available to a single instance of that type in millicores.
- instance_max_disk : integer
  
  The amount of disk available to a single instance of that type in gigabytes.
- usage_stats : dict::
  
  pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
  
  pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
  
  running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
  
  running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
  
  pending_deployments : integer
  
  The number of pending deployments in this instance config.
  
  running_deployments : integer
  
  The number of running deployments in this instance config.
default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

is_nat_enabled : boolean

Whether this cluster needs a NAT gateway or not.

hours : number/float

The number of hours used this month for this cluster.

patch_kubernetes_partitions(self, id, cluster_partition_id, *, instance_configs='DEFAULT', name='DEFAULT', labels='DEFAULT')¶

Update a Cluster Partition

Parameters:

id : integer

The ID of the cluster which this partition belongs to.

cluster_partition_id : integer

The ID of this cluster partition.

instance_configs : list, optional::

The instances configured for this cluster partition. - instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.

min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.

name : string, optional

The name of the cluster partition.

labels : list, optional

Labels associated with this partition.

Returns:

cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.

labels : list

Labels associated with this partition.

instance_configs : list::

The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.

instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.
instance_max_memory : integer

The amount of memory (RAM) available to a single instance of that type in megabytes.
instance_max_cpu : integer

The number of processor shares available to a single instance of that type in millicores.
instance_max_disk : integer

The amount of disk available to a single instance of that type in gigabytes.
usage_stats : dict::
- pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
- pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
- running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
- running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
- pending_deployments : integer
  
  The number of pending deployments in this instance config.
- running_deployments : integer
  
  The number of running deployments in this instance config.

default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

post_kubernetes(self, *, organization_id='DEFAULT', organization_slug='DEFAULT', is_nat_enabled='DEFAULT')¶

Create a Kubernetes Cluster

Parameters:

organization_id : string, optional: The id of this cluster’s organization.
organization_slug : string, optional: The slug of this cluster’s organization.
is_nat_enabled : boolean, optional: Whether this cluster needs a NAT gateway or not.

Returns:

id : integer

The ID of this cluster.

organization_id : string

The id of this cluster’s organization.

organization_name : string

The name of this cluster’s organization.

organization_slug : string

The slug of this cluster’s organization.

custom_partitions : boolean

Whether this cluster has a custom partition configuration.

cluster_partitions : list::

List of cluster partitions associated with this cluster. - cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.
labels : list

Labels associated with this partition.
instance_configs : list::
The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.
- instance_type : string
  
  An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
- min_instances : integer
  
  The minimum number of instances of that type in this cluster.
- max_instances : integer
  
  The maximum number of instances of that type in this cluster.
- instance_max_memory : integer
  
  The amount of memory (RAM) available to a single instance of that type in megabytes.
- instance_max_cpu : integer
  
  The number of processor shares available to a single instance of that type in millicores.
- instance_max_disk : integer
  
  The amount of disk available to a single instance of that type in gigabytes.
- usage_stats : dict::
  
  pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
  
  pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
  
  running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
  
  running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
  
  pending_deployments : integer
  
  The number of pending deployments in this instance config.
  
  running_deployments : integer
  
  The number of running deployments in this instance config.
default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

is_nat_enabled : boolean

Whether this cluster needs a NAT gateway or not.

hours : number/float

The number of hours used this month for this cluster.

post_kubernetes_partitions(self, id, instance_configs, name, labels)¶

Create a Cluster Partition for given cluster

Parameters:

id : integer

The ID of the cluster which this partition belongs to.

instance_configs : list::

The instances configured for this cluster partition. - instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.

min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.

name : string

The name of the cluster partition.

labels : list

Labels associated with this partition.

Returns:

cluster_partition_id : integer

The ID of this cluster partition.

name : string

The name of the cluster partition.

labels : list

Labels associated with this partition.

instance_configs : list::

The instances configured for this cluster partition. - instance_config_id : integer

The ID of this InstanceConfig.

instance_type : string

An EC2 instance type. Possible values include t2.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m5.12xlarge, c5.18xlarge, and p2.xlarge.
min_instances : integer

The minimum number of instances of that type in this cluster.
max_instances : integer

The maximum number of instances of that type in this cluster.
instance_max_memory : integer

The amount of memory (RAM) available to a single instance of that type in megabytes.
instance_max_cpu : integer

The number of processor shares available to a single instance of that type in millicores.
instance_max_disk : integer

The amount of disk available to a single instance of that type in gigabytes.
usage_stats : dict::
- pending_memory_requested : integer
  
  The sum of memory requests (in MB) for pending deployments in this instance config.
- pending_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for pending deployments in this instance config.
- running_memory_requested : integer
  
  The sum of memory requests (in MB) for running deployments in this instance config.
- running_cpu_requested : integer
  
  The sum of cpu requests (in millicores) for running deployments in this instance config.
- pending_deployments : integer
  
  The number of pending deployments in this instance config.
- running_deployments : integer
  
  The number of running deployments in this instance config.

default_instance_config_id : integer

The id of the InstanceConfig that is the default for this partition.

Credentials¶

class Credentials(session_kwargs, client, return_type='civis')¶

Methods

`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get a credential
`list`(self, \*[, type, remote_host_id, …])	List credentials
`list_shares`(self, id)	List users and groups permissioned on this object
`post`(self, type, username, password, \*[, …])	Create a credential
`post_authenticate`(self, url, …)	Authenticate against a remote host
`post_temporary`(self, id, \*[, duration])	Generate a temporary credential for accessing S3
`put`(self, id, type, username, password, \*)	Update an existing credential
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, 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.
state : string: The U.S. state for the credential. Only for VAN credentials.
created_at : string/time: The creation time for this credential.
updated_at : string/time: The last modification time for this credential.
default : boolean: Whether or not the credential is a default. Only for Database credentials.

list(self, *, type='DEFAULT', remote_host_id='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, Bitbucket, CASS/NCOA PAF, Certificate, Civis Platform, Custom, Database, Google, Github, Salesforce User, Salesforce Client, and TableauUser. Specify multiple values as a comma-separated list (e.g., “A,B”).
remote_host_id : integer, optional: The ID of the remote host associated with the credentials to return.
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.
state : string: The U.S. state for the credential. Only for VAN credentials.
created_at : string/time: The creation time for this credential.
updated_at : string/time: The last modification time for this credential.
default : boolean: Whether or not the credential is a default. Only for Database credentials.

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, type, username, password, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', state='DEFAULT', system_credential='DEFAULT', default='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.
state : string, optional: The U.S. state for the credential. Only for VAN credentials.
system_credential : boolean, optional
default : boolean, optional: Whether or not the credential is a default. Only for Database credentials.

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.
state : string: The U.S. state for the credential. Only for VAN credentials.
created_at : string/time: The creation time for this credential.
updated_at : string/time: The last modification time for this credential.
default : boolean: Whether or not the credential is a default. Only for Database credentials.

post_authenticate(self, 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::Bitbucket, RemoteHostTypes::GitSSH, RemoteHostTypes::Github, RemoteHostTypes::GoogleDoc, RemoteHostTypes::JDBC, RemoteHostTypes::Postgres, RemoteHostTypes::Redshift, RemoteHostTypes::S3Storage, and RemoteHostTypes::Salesforce
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.
state : string: The U.S. state for the credential. Only for VAN credentials.
created_at : string/time: The creation time for this credential.
updated_at : string/time: The last modification time for this credential.
default : boolean: Whether or not the credential is a default. Only for Database credentials.

post_temporary(self, 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(self, id, type, username, password, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', state='DEFAULT', system_credential='DEFAULT', default='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.
state : string, optional: The U.S. state for the credential. Only for VAN credentials.
system_credential : boolean, optional
default : boolean, optional: Whether or not the credential is a default. Only for Database credentials.

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.
state : string: The U.S. state for the credential. Only for VAN credentials.
created_at : string/time: The creation time for this credential.
updated_at : string/time: The last modification time for this credential.
default : boolean: Whether or not the credential is a default. Only for Database credentials.

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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, client, return_type='civis')¶

Methods

`delete_whitelist_ips`(self, id, whitelisted_ip_id)	Remove a whitelisted IP address
`get`(self, id)	Show database information
`get_whitelist_ips`(self, id, whitelisted_ip_id)	View details about a whitelisted IP
`list`(self)	List databases
`list_advanced_settings`(self, id)	Get the advanced settings for this database
`list_schemas`(self, id)	List schemas in this database
`list_whitelist_ips`(self, id)	List whitelisted IPs for the specified database
`patch_advanced_settings`(self, id, \*[, …])	Update the advanced settings for this database
`post_schemas_scan`(self, id, schema, \*[, …])	Creates and enqueues a schema scanner job
`post_whitelist_ips`(self, id, subnet_mask)	Whitelist an IP address
`put_advanced_settings`(self, id, …)	Edit the advanced settings for this database

delete_whitelist_ips(self, 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(self, id)¶

Show database information

Parameters:	id : integer The ID for the database.
Returns:	id : integer The ID for the database. name : string The name of the database. adapter : string The type of the database.

get_whitelist_ips(self, 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(self)¶

List databases

Returns:	id : integer The ID for the database. name : string The name of the database. adapter : string The type of the database.

list_advanced_settings(self, id)¶

Get the advanced settings for this database

Parameters:	id : integer The ID of the database this advanced settings object belongs to.
Returns:	export_caching_enabled : boolean Whether or not caching is enabled for export jobs run on this database server.

list_schemas(self, 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(self, 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.

patch_advanced_settings(self, id, *, export_caching_enabled='DEFAULT')¶

Update the advanced settings for this database

Parameters:	id : integer The ID of the database this advanced settings object belongs to. export_caching_enabled : boolean, optional Whether or not caching is enabled for export jobs run on this database server.
Returns:	export_caching_enabled : boolean Whether or not caching is enabled for export jobs run on this database server.

post_schemas_scan(self, id, schema, *, stats_priority='DEFAULT')¶

Creates and enqueues a schema scanner job

Parameters:

id : integer: The ID of the database.
schema : string: The name of the schema.
stats_priority : string, optional: When to sync table statistics for every table in the schema. Valid options are the following. Option: ‘flag’ means to flag stats for the next scheduled run of a full table scan on the database. Option: ‘block’ means to block this job on stats syncing. Option: ‘queue’ means to queue a separate job for syncing stats and do not block this job on the queued job. Defaults to ‘flag’

Returns:

job_id : integer: The ID of the job created.
run_id : integer: The ID of the run created.

post_whitelist_ips(self, 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.

put_advanced_settings(self, id, export_caching_enabled)¶

Edit the advanced settings for this database

Parameters:	id : integer The ID of the database this advanced settings object belongs to. export_caching_enabled : boolean Whether or not caching is enabled for export jobs run on this database server.
Returns:	export_caching_enabled : boolean Whether or not caching is enabled for export jobs run on this database server.

Endpoints¶

class Endpoints(session_kwargs, client, return_type='civis')¶

Methods

list(self) List API endpoints

list(self)¶

List API endpoints

Returns:	None Response code 200: success

Enhancements¶

class Enhancements(session_kwargs, client, return_type='civis')¶

Methods

`delete_cass_ncoa_projects`(self, id, project_id)	Remove a CASS/NCOA Enhancement from a project
`delete_cass_ncoa_runs`(self, id, run_id)	Cancel a run
`delete_cass_ncoa_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_cass_ncoa_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_civis_data_match_projects`(self, id, …)	Remove a Civis Data Match Enhancement from a project
`delete_civis_data_match_runs`(self, id, run_id)	Cancel a run
`delete_civis_data_match_shares_groups`(self, …)	Revoke the permissions a group has on this object
`delete_civis_data_match_shares_users`(self, …)	Revoke the permissions a user has on this object
`delete_geocode_projects`(self, id, project_id)	Remove a Geocode Enhancement from a project
`delete_geocode_runs`(self, id, run_id)	Cancel a run
`delete_geocode_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_geocode_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get_cass_ncoa`(self, id)	Get a CASS/NCOA Enhancement
`get_cass_ncoa_runs`(self, id, run_id)	Check status of a run
`get_civis_data_match`(self, id)	Get a Civis Data Match Enhancement
`get_civis_data_match_runs`(self, id, run_id)	Check status of a run
`get_geocode`(self, id)	Get a Geocode Enhancement
`get_geocode_runs`(self, id, run_id)	Check status of a run
`list`(self, \*[, type, author, status, …])	List Enhancements
`list_cass_ncoa_projects`(self, id, \*[, hidden])	List the projects a CASS/NCOA Enhancement belongs to
`list_cass_ncoa_runs`(self, id, \*[, limit, …])	List runs for the given cass_ncoa
`list_cass_ncoa_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_cass_ncoa_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`list_cass_ncoa_shares`(self, id)	List users and groups permissioned on this object
`list_civis_data_match_projects`(self, id, \*)	List the projects a Civis Data Match Enhancement belongs to
`list_civis_data_match_runs`(self, id, \*[, …])	List runs for the given civis_data_match
`list_civis_data_match_runs_logs`(self, id, …)	Get the logs for a run
`list_civis_data_match_runs_outputs`(self, id, …)	List the outputs for a run
`list_civis_data_match_shares`(self, id)	List users and groups permissioned on this object
`list_field_mapping`(self)	List the fields in a field mapping for Civis Data Match, Data Unification, and Table Deduplication jobs
`list_geocode_projects`(self, id, \*[, hidden])	List the projects a Geocode Enhancement belongs to
`list_geocode_runs`(self, id, \*[, limit, …])	List runs for the given geocode
`list_geocode_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_geocode_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`list_geocode_shares`(self, id)	List users and groups permissioned on this object
`list_types`(self)	List available enhancement types
`patch_cass_ncoa`(self, id, \*[, name, …])	Update some attributes of this CASS/NCOA Enhancement
`patch_civis_data_match`(self, id, \*[, name, …])	Update some attributes of this Civis Data Match Enhancement
`patch_geocode`(self, id, \*[, name, …])	Update some attributes of this Geocode Enhancement
`post_cass_ncoa`(self, name, source, \*[, …])	Create a CASS/NCOA Enhancement
`post_cass_ncoa_cancel`(self, id)	Cancel a run
`post_cass_ncoa_runs`(self, id)	Start a run
`post_civis_data_match`(self, name, …[, …])	Create a Civis Data Match Enhancement
`post_civis_data_match_cancel`(self, id)	Cancel a run
`post_civis_data_match_clone`(self, id, \*[, …])	Clone this Civis Data Match Enhancement
`post_civis_data_match_runs`(self, id)	Start a run
`post_geocode`(self, name, remote_host_id, …)	Create a Geocode Enhancement
`post_geocode_cancel`(self, id)	Cancel a run
`post_geocode_runs`(self, id)	Start a run
`put_cass_ncoa`(self, id, name, source, \*[, …])	Replace all attributes of this CASS/NCOA Enhancement
`put_cass_ncoa_archive`(self, id, status)	Update the archive status of this object
`put_cass_ncoa_projects`(self, id, project_id)	Add a CASS/NCOA Enhancement to a project
`put_cass_ncoa_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_cass_ncoa_shares_users`(self, id, …[, …])	Set the permissions users have on this object
`put_civis_data_match`(self, id, name, …[, …])	Replace all attributes of this Civis Data Match Enhancement
`put_civis_data_match_archive`(self, id, status)	Update the archive status of this object
`put_civis_data_match_projects`(self, id, …)	Add a Civis Data Match Enhancement to a project
`put_civis_data_match_shares_groups`(self, id, …)	Set the permissions groups has on this object
`put_civis_data_match_shares_users`(self, id, …)	Set the permissions users have on this object
`put_geocode`(self, id, name, remote_host_id, …)	Replace all attributes of this Geocode Enhancement
`put_geocode_archive`(self, id, status)	Update the archive status of this object
`put_geocode_projects`(self, id, project_id)	Add a Geocode Enhancement to a project
`put_geocode_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_geocode_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object

delete_cass_ncoa_projects(self, id, project_id)¶

Remove a CASS/NCOA Enhancement from a project

Parameters:	id : integer The ID of the CASS/NCOA Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_cass_ncoa_runs(self, 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

delete_cass_ncoa_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_cass_ncoa_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_civis_data_match_projects(self, id, project_id)¶

Remove a Civis Data Match Enhancement from a project

Parameters:	id : integer The ID of the Civis Data Match Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_civis_data_match_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the civis_data_match. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_civis_data_match_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_civis_data_match_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_geocode_projects(self, id, project_id)¶

Remove a Geocode Enhancement from a project

Parameters:	id : integer The ID of the Geocode Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_geocode_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the geocode. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_geocode_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_geocode_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get_cass_ncoa(self, id)¶

Get a CASS/NCOA Enhancement

Parameters:

id : integer

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

archived : string

The archival status of the requested item(s).

get_cass_ncoa_runs(self, 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.

get_civis_data_match(self, id)¶

Get a Civis Data Match Enhancement

Parameters:

id : integer

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

get_civis_data_match_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the civis_data_match.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
civis_data_match_id : integer: The ID of the civis_data_match.
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_geocode(self, id)¶

Get a Geocode Enhancement

Parameters:

id : integer

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

multipart_key : list

The source table primary key.

limiting_sql : string

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string

The output table schema.

target_table : string

The output table name.

country : string

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

archived : string

The archival status of the requested item(s).

get_geocode_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the geocode.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
geocode_id : integer: The ID of the geocode.
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(self, *, 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 items of these types.
author : string, optional: If specified, return items from this author. Must use user IDs. A comma separated list of IDs is also accepted to return items from multiple authors.
status : string, optional: If specified, returns items 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 item(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 job.

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 item(s).

list_cass_ncoa_projects(self, id, *, hidden='DEFAULT')¶

List the projects a CASS/NCOA Enhancement belongs to

Parameters:

id : integer: The ID of the CASS/NCOA Enhancement.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_cass_ncoa_runs(self, 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(self, 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(self, 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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_cass_ncoa_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_civis_data_match_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Civis Data Match Enhancement belongs to

Parameters:

id : integer: The ID of the Civis Data Match Enhancement.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_civis_data_match_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given civis_data_match

Parameters:

id : integer: The ID of the civis_data_match.
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.
civis_data_match_id : integer: The ID of the civis_data_match.
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_civis_data_match_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:

id : integer: The ID of the civis_data_match.
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_civis_data_match_runs_outputs(self, 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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_civis_data_match_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_field_mapping(self)¶

List the fields in a field mapping for Civis Data Match, Data Unification, and Table Deduplication jobs

Returns:	field : string The name of the field. description : string The description of the field.

list_geocode_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Geocode Enhancement belongs to

Parameters:

id : integer: The ID of the Geocode Enhancement.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_geocode_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given geocode

Parameters:

id : integer: The ID of the geocode.
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.
geocode_id : integer: The ID of the geocode.
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_geocode_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the geocode. 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_geocode_runs_outputs(self, 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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_geocode_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self)¶

List available enhancement types

Returns:	name : string The name of the type.

patch_cass_ncoa(self, 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 job.

schedule : dict, optional::

scheduled : boolean

If the item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

archived : string

The archival status of the requested item(s).

patch_civis_data_match(self, id, *, name='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', input_field_mapping='DEFAULT', input_table='DEFAULT', match_target_id='DEFAULT', output_table='DEFAULT', max_matches='DEFAULT', threshold='DEFAULT', archived='DEFAULT')¶

Update some attributes of this Civis Data Match Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string, optional

The name of the enhancement job.

schedule : dict, optional::

scheduled : boolean

If the item 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.

input_field_mapping : dict, optional

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict, optional::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer, optional

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict, optional::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer, optional

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float, optional

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean, optional

Whether the Civis Data Match Job has been archived.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

patch_geocode(self, id, *, name='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT', source_schema_and_table='DEFAULT', multipart_key='DEFAULT', limiting_sql='DEFAULT', target_schema='DEFAULT', target_table='DEFAULT', country='DEFAULT', provider='DEFAULT', output_address='DEFAULT')¶

Update some attributes of this Geocode Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string, optional

The name of the enhancement job.

schedule : dict, optional::

scheduled : boolean

If the item 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.

remote_host_id : integer, optional

The ID of the remote host.

credential_id : integer, optional

The ID of the remote host credential.

source_schema_and_table : string, optional

The source database schema and table.

multipart_key : list, optional

The source table primary key.

limiting_sql : string, optional

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string, optional

The output table schema.

target_table : string, optional

The output table name.

country : string, optional

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string, optional

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean, optional

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

multipart_key : list

The source table primary key.

limiting_sql : string

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string

The output table schema.

target_table : string

The output table name.

country : string

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

archived : string

The archival status of the requested item(s).

post_cass_ncoa(self, 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 job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

archived : string

The archival status of the requested item(s).

post_cass_ncoa_cancel(self, 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(self, 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.

post_civis_data_match(self, name, input_field_mapping, input_table, match_target_id, output_table, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', max_matches='DEFAULT', threshold='DEFAULT', archived='DEFAULT')¶

Create a Civis Data Match Enhancement

Parameters:

name : string

The name of the enhancement job.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

schedule : dict, optional::

scheduled : boolean

If the item 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.

max_matches : integer, optional

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float, optional

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean, optional

Whether the Civis Data Match Job has been archived.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

post_civis_data_match_cancel(self, 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_civis_data_match_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this Civis Data Match Enhancement

Parameters:

id : integer: The ID for the enhancement.
clone_schedule : boolean, optional: If true, also copy the schedule to the new enhancement.
clone_triggers : boolean, optional: If true, also copy the triggers to the new enhancement.
clone_notifications : boolean, optional: If true, also copy the notifications to the new enhancement.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

post_civis_data_match_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the civis_data_match.

Returns:

id : integer: The ID of the run.
civis_data_match_id : integer: The ID of the civis_data_match.
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_geocode(self, name, remote_host_id, credential_id, source_schema_and_table, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', multipart_key='DEFAULT', limiting_sql='DEFAULT', target_schema='DEFAULT', target_table='DEFAULT', country='DEFAULT', provider='DEFAULT', output_address='DEFAULT')¶

Create a Geocode Enhancement

Parameters:

name : string

The name of the enhancement job.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

schedule : dict, optional::

scheduled : boolean

If the item 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.

multipart_key : list, optional

The source table primary key.

limiting_sql : string, optional

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string, optional

The output table schema.

target_table : string, optional

The output table name.

country : string, optional

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string, optional

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean, optional

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

multipart_key : list

The source table primary key.

limiting_sql : string

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string

The output table schema.

target_table : string

The output table name.

country : string

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

archived : string

The archival status of the requested item(s).

post_geocode_cancel(self, 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_geocode_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the geocode.

Returns:

id : integer: The ID of the run.
geocode_id : integer: The ID of the geocode.
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(self, 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 job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

archived : string

The archival status of the requested item(s).

put_cass_ncoa_archive(self, 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 job.

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 item 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 for the source table. “WHERE” should be omitted (e.g. state=’IL’).

archived : string

The archival status of the requested item(s).

put_cass_ncoa_projects(self, id, project_id)¶

Add a CASS/NCOA Enhancement to a project

Parameters:	id : integer The ID of the CASS/NCOA Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_cass_ncoa_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_cass_ncoa_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_civis_data_match(self, id, name, input_field_mapping, input_table, match_target_id, output_table, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', max_matches='DEFAULT', threshold='DEFAULT', archived='DEFAULT')¶

Replace all attributes of this Civis Data Match Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

schedule : dict, optional::

scheduled : boolean

If the item 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.

max_matches : integer, optional

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float, optional

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean, optional

Whether the Civis Data Match Job has been archived.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

put_civis_data_match_archive(self, 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 job.

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 item 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.

input_field_mapping : dict

The column mapping for the input table. See /enhancements/field_mapping for list of valid fields.

input_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

match_target_id : integer

The ID of the Civis Data match target. See /match_targets for IDs.

output_table : dict::

database_name : string

The Redshift database name for the table.
schema : string

The schema name for the table.
table : string

The table name.

max_matches : integer

The maximum number of matches per record in the input table to return. Must be between 0 and 10. 0 returns all matches.

threshold : number/float

The score threshold (between 0 and 1). Matches below this threshold will not be returned. The default value is 0.5.

archived : boolean

Whether the Civis Data Match Job has been archived.

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.

put_civis_data_match_projects(self, id, project_id)¶

Add a Civis Data Match Enhancement to a project

Parameters:	id : integer The ID of the Civis Data Match Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_civis_data_match_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_civis_data_match_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_geocode(self, id, name, remote_host_id, credential_id, source_schema_and_table, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', multipart_key='DEFAULT', limiting_sql='DEFAULT', target_schema='DEFAULT', target_table='DEFAULT', country='DEFAULT', provider='DEFAULT', output_address='DEFAULT')¶

Replace all attributes of this Geocode Enhancement

Parameters:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

schedule : dict, optional::

scheduled : boolean

If the item 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.

multipart_key : list, optional

The source table primary key.

limiting_sql : string, optional

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string, optional

The output table schema.

target_table : string, optional

The output table name.

country : string, optional

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string, optional

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean, optional

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

Returns:

id : integer

The ID for the enhancement.

name : string

The name of the enhancement job.

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 item 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.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

multipart_key : list

The source table primary key.

limiting_sql : string

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string

The output table schema.

target_table : string

The output table name.

country : string

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

archived : string

The archival status of the requested item(s).

put_geocode_archive(self, 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 job.

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 item 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.

remote_host_id : integer

The ID of the remote host.

credential_id : integer

The ID of the remote host credential.

source_schema_and_table : string

The source database schema and table.

multipart_key : list

The source table primary key.

limiting_sql : string

The limiting SQL for the source table. “WHERE” should be omitted (e.g. state=’IL’).

target_schema : string

The output table schema.

target_table : string

The output table name.

country : string

The country of the addresses to be geocoded; either ‘us’ or ‘ca’.

provider : string

The geocoding provider; one of postgis, nominatim, and geocoder_ca.

output_address : boolean

Whether to output the parsed address. Only guaranteed for the ‘postgis’ provider.

archived : string

The archival status of the requested item(s).

put_geocode_projects(self, id, project_id)¶

Add a Geocode Enhancement to a project

Parameters:	id : integer The ID of the Geocode Enhancement. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_geocode_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_geocode_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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, client, return_type='civis')¶

Methods

`delete_files_csv_runs`(self, id, run_id)	Cancel a run
`get_files_csv`(self, id)	Get a CSV Export
`get_files_csv_runs`(self, id, run_id)	Check status of a run
`list`(self, \*[, type, author, status, …])	List
`list_files_csv_runs`(self, id, \*[, limit, …])	List runs for the given csv_export
`list_files_csv_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_files_csv_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`patch_files_csv`(self, id, \*[, name, …])	Update some attributes of this CSV Export
`post_files_csv`(self, source, destination, \*)	Create a CSV Export
`post_files_csv_runs`(self, id)	Start a run
`put_files_csv`(self, id, source, destination, \*)	Replace all attributes of this CSV Export
`put_files_csv_archive`(self, id, status)	Update the archive status of this object

delete_files_csv_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the csv_export. run_id : integer The ID of the run.
Returns:	None Response code 202: success

get_files_csv(self, id)¶

Get a CSV Export

Parameters:

id : integer

Returns:

id : integer

The ID of this Csv Export job.

name : string

The name of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

get_files_csv_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the csv_export.
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.
output_cached_on : string/time: The time that the output was originally exported, if a cache entry was used by the run.

list(self, *, 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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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.

list_files_csv_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given csv_export

Parameters:

id : integer: The ID of the csv_export.
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
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_files_csv_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the csv_export. 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_files_csv_runs_outputs(self, 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 csv_export.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

patch_files_csv(self, id, *, name='DEFAULT', source='DEFAULT', destination='DEFAULT', include_header='DEFAULT', compression='DEFAULT', column_delimiter='DEFAULT', hidden='DEFAULT', force_multifile='DEFAULT', max_file_size='DEFAULT')¶

Update some attributes of this CSV Export

Parameters:

id : integer

The ID of this Csv Export job.

name : string, optional

The name of this Csv Export job.

source : dict, optional::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict, optional::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean, optional

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string, optional

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string, optional

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean, optional

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean, optional

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer, optional

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID of this Csv Export job.

name : string

The name of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

post_files_csv(self, source, destination, *, name='DEFAULT', include_header='DEFAULT', compression='DEFAULT', column_delimiter='DEFAULT', hidden='DEFAULT', force_multifile='DEFAULT', max_file_size='DEFAULT')¶

Create a CSV Export

Parameters:

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

name : string, optional

The name of this Csv Export job.

include_header : boolean, optional

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string, optional

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string, optional

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean, optional

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean, optional

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer, optional

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID of this Csv Export job.

name : string

The name of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

post_files_csv_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the csv_export.

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.
output_cached_on : string/time: The time that the output was originally exported, if a cache entry was used by the run.

put_files_csv(self, id, source, destination, *, name='DEFAULT', include_header='DEFAULT', compression='DEFAULT', column_delimiter='DEFAULT', hidden='DEFAULT', force_multifile='DEFAULT', max_file_size='DEFAULT')¶

Replace all attributes of this CSV Export

Parameters:

id : integer

The ID of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

name : string, optional

The name of this Csv Export job.

include_header : boolean, optional

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string, optional

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string, optional

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean, optional

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean, optional

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer, optional

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID of this Csv Export job.

name : string

The name of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

put_files_csv_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID of this Csv Export job.

name : string

The name of this Csv Export job.

source : dict::

sql : string

The SQL query for this Csv Export job
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.

destination : dict::

filename_prefix : string

The prefix of the name of the file returned to the user.
storage_path : dict::
- file_path : string
  
  The path within the bucket where the exported file will be saved. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”
- storage_host_id : integer
  
  The ID of the destination storage host.
- credential_id : integer
  
  The ID of the credentials for the destination storage host.
- existing_files : string
  
  Notifies the job of what to do in the case that the exported file already exists at the provided path.One of: fail, append, overwrite. Default: fail. If “append” is specified,the new file will always be added to the provided path. If “overwrite” is specifiedall existing files at the provided path will be deleted and the new file will be added.By default, or if “fail” is specified, the export will fail if a file exists at the provided path.

include_header : boolean

A boolean value indicating whether or not the header should be included. Defaults to true.

compression : string

The compression of the output file. Valid arguments are “gzip” and “none”. Defaults to “gzip”.

column_delimiter : string

The column delimiter for the output file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

hidden : boolean

A boolean value indicating whether or not this request should be hidden. Defaults to false.

force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false

max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

Files¶

class Files(session_kwargs, client, return_type='civis')¶

Methods

`delete_projects`(self, id, project_id)	Remove a File from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id, \*[, link_expires_at, inline])	Get details about a file
`get_preprocess_csv`(self, id)	Get a Preprocess CSV
`list_projects`(self, id, \*[, hidden])	List the projects a File belongs to
`list_shares`(self, id)	List users and groups permissioned on this object
`patch`(self, id, \*[, name, expires_at])	Update details about a file
`patch_preprocess_csv`(self, id, \*[, …])	Update some attributes of this Preprocess CSV
`post`(self, name, \*[, expires_at])	Initiate an upload of a file into the platform
`post_multipart`(self, name, num_parts, \*[, …])	Initiate a multipart upload
`post_multipart_complete`(self, id)	Complete a multipart upload
`post_preprocess_csv`(self, file_id, \*[, …])	Create a Preprocess CSV
`put`(self, id, name, expires_at)	Update details about a file
`put_preprocess_csv`(self, id, file_id, \*[, …])	Replace all attributes of this Preprocess CSV
`put_preprocess_csv_archive`(self, id, status)	Update the archive status of this object
`put_projects`(self, id, project_id)	Add a File to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_projects(self, id, project_id)¶

Remove a File from a project

Parameters:	id : integer The ID of the File. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id, *, link_expires_at='DEFAULT', inline='DEFAULT')¶

Get details about a file

Parameters:

id : integer: The ID of the file.
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.
inline : boolean, optional: If true, will return a url that can be displayed inline in HTML

Returns:

id : integer

The ID of the file.

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.

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.

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.

detected_info : dict::

include_header : boolean

A boolean value indicating whether or not the first row of the file is a header row.
column_delimiter : string

The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
compression : string

The type of compression of the file. One of “gzip”, or “none”.
table_columns : list::
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type” - name : string

The column name.
- sql_type : string
  
  The SQL type of the column.

get_preprocess_csv(self, id)¶

Get a Preprocess CSV

Parameters:

id : integer

Returns:

id : integer: The ID of the job created.
file_id : integer: The ID of the file.
in_place : boolean: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean: The hidden status of the item.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a File belongs to

Parameters:

id : integer: The ID of the File.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, id, *, name='DEFAULT', expires_at='DEFAULT')¶

Update details about a file

Parameters:

id : integer: The ID of the file.
name : string, optional: The file name. The extension must match the previous extension.
expires_at : string/date-time, optional: The date and time the file will expire.

Returns:

id : integer

The ID of the file.

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.

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.

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.

detected_info : dict::

include_header : boolean

A boolean value indicating whether or not the first row of the file is a header row.
column_delimiter : string

The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
compression : string

The type of compression of the file. One of “gzip”, or “none”.
table_columns : list::
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type” - name : string

The column name.
- sql_type : string
  
  The SQL type of the column.

patch_preprocess_csv(self, id, *, file_id='DEFAULT', in_place='DEFAULT', detect_table_columns='DEFAULT', force_character_set_conversion='DEFAULT', include_header='DEFAULT', column_delimiter='DEFAULT')¶

Update some attributes of this Preprocess CSV

Parameters:

id : integer: The ID of the job created.
file_id : integer, optional: The ID of the file.
in_place : boolean, optional: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean, optional: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean, optional: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean, optional: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string, optional: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.

Returns:

id : integer: The ID of the job created.
file_id : integer: The ID of the file.
in_place : boolean: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean: The hidden status of the item.

post(self, 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.
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(self, 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.
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(self, id)¶

Complete a multipart upload

Parameters:	id : integer The ID of the file.
Returns:	None Response code 204: success

post_preprocess_csv(self, file_id, *, in_place='DEFAULT', detect_table_columns='DEFAULT', force_character_set_conversion='DEFAULT', include_header='DEFAULT', column_delimiter='DEFAULT', hidden='DEFAULT')¶

Create a Preprocess CSV

Parameters:

file_id : integer: The ID of the file.
in_place : boolean, optional: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean, optional: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean, optional: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean, optional: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string, optional: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean, optional: The hidden status of the item.

Returns:

id : integer: The ID of the job created.
file_id : integer: The ID of the file.
in_place : boolean: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean: The hidden status of the item.

put(self, id, name, expires_at)¶

Update details about a file

Parameters:

id : integer: The ID of the file.
name : string: The file name. The extension must match the previous extension.
expires_at : string/date-time: The date and time the file will expire.

Returns:

id : integer

The ID of the file.

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.

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.

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.

detected_info : dict::

include_header : boolean

A boolean value indicating whether or not the first row of the file is a header row.
column_delimiter : string

The column delimiter for the file. One of “comma”, “tab”, or “pipe”.
compression : string

The type of compression of the file. One of “gzip”, or “none”.
table_columns : list::
An array of hashes corresponding to the columns in the file. Each hash should have keys for column “name” and “sql_type” - name : string

The column name.
- sql_type : string
  
  The SQL type of the column.

put_preprocess_csv(self, id, file_id, *, in_place='DEFAULT', detect_table_columns='DEFAULT', force_character_set_conversion='DEFAULT', include_header='DEFAULT', column_delimiter='DEFAULT')¶

Replace all attributes of this Preprocess CSV

Parameters:

id : integer: The ID of the job created.
file_id : integer: The ID of the file.
in_place : boolean, optional: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean, optional: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean, optional: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean, optional: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string, optional: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.

Returns:

id : integer: The ID of the job created.
file_id : integer: The ID of the file.
in_place : boolean: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean: The hidden status of the item.

put_preprocess_csv_archive(self, 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 job created.
file_id : integer: The ID of the file.
in_place : boolean: If true, the file is cleaned in place. If false, a new file ID is created. Defaults to true.
detect_table_columns : boolean: If true, detect the table columns in the file including the sql types. If false, skip table column detection.Defaults to false.
force_character_set_conversion : boolean: If true, the file will always be converted to UTF-8 and any character that cannot be converted will be discarded. If false, the character set conversion will only run if the detected character set is not compatible with UTF-8 (e.g., UTF-8, ASCII).
include_header : boolean: A boolean value indicating whether or not the first row of the file is a header row. If not provided, will attempt to auto-detect whether a header row is present.
column_delimiter : string: The column delimiter for the file. One of “comma”, “tab”, or “pipe”. If not provided, the column delimiter will be auto-detected.
hidden : boolean: The hidden status of the item.

put_projects(self, id, project_id)¶

Add a File to a project

Parameters:	id : integer The ID of the File. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Git_Repos¶

civis.resources._resources.Git_Repos¶: alias of civis.resources._resources.GitRepos

Groups¶

class Groups(session_kwargs, client, return_type='civis')¶

Methods

`delete_members`(self, id, user_id)	Remove a user from a group
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get a Group
`list`(self, \*[, query, permission, …])	List Groups
`list_shares`(self, id)	List users and groups permissioned on this object
`patch`(self, id, \*[, name, description, …])	Update some attributes of this Group
`post`(self, name, \*[, description, slug, …])	Create a Group
`put`(self, id, name, \*[, description, slug, …])	Replace all attributes of this Group
`put_members`(self, id, user_id)	Add a user to a group
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_members(self, id, user_id)¶

Remove a user from a group

Parameters:	id : integer The ID of the group. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Get a Group

Parameters:

id : integer

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.

description : string

The description of the group.

slug : string

The slug for this group.

organization_id : integer

The ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

must_agree_to_eula : boolean

Whether or not members of this group must sign the EULA.

default_otp_required_for_login : boolean

The two factor authentication requirement for this group.

role_ids : list

An array of ids of all the roles this group has.

default_time_zone : string

The default time zone of this group.

default_jobs_label : string

The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_notebooks_label : string

The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_services_label : string

The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

members : list::

The members of this group. - 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.
email : string

This user’s email address.
primary_group_id : integer

The ID of the primary group of this user.

list(self, *, query='DEFAULT', permission='DEFAULT', include_members='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. Infix matching is supported (e.g., “query=group” will return “group” and “group of people” and “my group” and “my group of people”).
permission : string, optional: A permissions string, one of “read”, “write”, or “manage”. Lists only groups for which the current user has that permission.
include_members : boolean, optional: Show members of the group.
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 ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

members : list::

The members of this group. - 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_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, id, *, name='DEFAULT', description='DEFAULT', slug='DEFAULT', organization_id='DEFAULT', must_agree_to_eula='DEFAULT', default_otp_required_for_login='DEFAULT', role_ids='DEFAULT', default_time_zone='DEFAULT', default_jobs_label='DEFAULT', default_notebooks_label='DEFAULT', default_services_label='DEFAULT')¶

Update some attributes of this Group

Parameters:

id : integer: The ID of this group.
name : string, optional: This group’s name.
description : string, optional: The description of the group.
slug : string, optional: The slug for this group.
organization_id : integer, optional: The ID of the organization this group belongs to.
must_agree_to_eula : boolean, optional: Whether or not members of this group must sign the EULA.
default_otp_required_for_login : boolean, optional: The two factor authentication requirement for this group.
role_ids : list, optional: An array of ids of all the roles this group has.
default_time_zone : string, optional: The default time zone of this group.
default_jobs_label : string, optional: The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_notebooks_label : string, optional: The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_services_label : string, optional: The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

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.

description : string

The description of the group.

slug : string

The slug for this group.

organization_id : integer

The ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

must_agree_to_eula : boolean

Whether or not members of this group must sign the EULA.

default_otp_required_for_login : boolean

The two factor authentication requirement for this group.

role_ids : list

An array of ids of all the roles this group has.

default_time_zone : string

The default time zone of this group.

default_jobs_label : string

The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_notebooks_label : string

The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_services_label : string

The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

members : list::

The members of this group. - 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.
email : string

This user’s email address.
primary_group_id : integer

The ID of the primary group of this user.

post(self, name, *, description='DEFAULT', slug='DEFAULT', organization_id='DEFAULT', must_agree_to_eula='DEFAULT', default_otp_required_for_login='DEFAULT', role_ids='DEFAULT', default_time_zone='DEFAULT', default_jobs_label='DEFAULT', default_notebooks_label='DEFAULT', default_services_label='DEFAULT')¶

Create a Group

Parameters:

name : string: This group’s name.
description : string, optional: The description of the group.
slug : string, optional: The slug for this group.
organization_id : integer, optional: The ID of the organization this group belongs to.
must_agree_to_eula : boolean, optional: Whether or not members of this group must sign the EULA.
default_otp_required_for_login : boolean, optional: The two factor authentication requirement for this group.
role_ids : list, optional: An array of ids of all the roles this group has.
default_time_zone : string, optional: The default time zone of this group.
default_jobs_label : string, optional: The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_notebooks_label : string, optional: The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_services_label : string, optional: The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

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.

description : string

The description of the group.

slug : string

The slug for this group.

organization_id : integer

The ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

must_agree_to_eula : boolean

Whether or not members of this group must sign the EULA.

default_otp_required_for_login : boolean

The two factor authentication requirement for this group.

role_ids : list

An array of ids of all the roles this group has.

default_time_zone : string

The default time zone of this group.

default_jobs_label : string

The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_notebooks_label : string

The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_services_label : string

The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

members : list::

The members of this group. - 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.
email : string

This user’s email address.
primary_group_id : integer

The ID of the primary group of this user.

put(self, id, name, *, description='DEFAULT', slug='DEFAULT', organization_id='DEFAULT', must_agree_to_eula='DEFAULT', default_otp_required_for_login='DEFAULT', role_ids='DEFAULT', default_time_zone='DEFAULT', default_jobs_label='DEFAULT', default_notebooks_label='DEFAULT', default_services_label='DEFAULT')¶

Replace all attributes of this Group

Parameters:

id : integer: The ID of this group.
name : string: This group’s name.
description : string, optional: The description of the group.
slug : string, optional: The slug for this group.
organization_id : integer, optional: The ID of the organization this group belongs to.
must_agree_to_eula : boolean, optional: Whether or not members of this group must sign the EULA.
default_otp_required_for_login : boolean, optional: The two factor authentication requirement for this group.
role_ids : list, optional: An array of ids of all the roles this group has.
default_time_zone : string, optional: The default time zone of this group.
default_jobs_label : string, optional: The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_notebooks_label : string, optional: The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.
default_services_label : string, optional: The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

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.

description : string

The description of the group.

slug : string

The slug for this group.

organization_id : integer

The ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

must_agree_to_eula : boolean

Whether or not members of this group must sign the EULA.

default_otp_required_for_login : boolean

The two factor authentication requirement for this group.

role_ids : list

An array of ids of all the roles this group has.

default_time_zone : string

The default time zone of this group.

default_jobs_label : string

The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_notebooks_label : string

The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_services_label : string

The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

members : list::

The members of this group. - 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.
email : string

This user’s email address.
primary_group_id : integer

The ID of the primary group of this user.

put_members(self, id, user_id)¶

Add a user to a group

Parameters:

id : integer: The ID of the group.
user_id : integer: The ID of the user.

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.

description : string

The description of the group.

slug : string

The slug for this group.

organization_id : integer

The ID of the organization this group belongs to.

organization_name : string

The name of the organization this group belongs to.

member_count : integer

The total number of members in this group.

must_agree_to_eula : boolean

Whether or not members of this group must sign the EULA.

default_otp_required_for_login : boolean

The two factor authentication requirement for this group.

role_ids : list

An array of ids of all the roles this group has.

default_time_zone : string

The default time zone of this group.

default_jobs_label : string

The default partition label for jobs of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_notebooks_label : string

The default partition label for notebooks of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

default_services_label : string

The default partition label for services of this group. Only available if custom_partitions feature flag is set. Do not use this attribute as it may break in the future.

members : list::

The members of this group. - 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.
email : string

This user’s email address.
primary_group_id : integer

The ID of the primary group of this user.

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Imports¶

class Imports(session_kwargs, client, return_type='civis')¶

Methods

`delete_files_csv_runs`(self, id, run_id)	Cancel a run
`delete_files_runs`(self, id, run_id)	Cancel a run
`delete_projects`(self, id, project_id)	Remove an Import from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get details about an import
`get_batches`(self, id)	Get details about a batch import
`get_files_csv`(self, id)	Get a CSV Import
`get_files_csv_runs`(self, id, run_id)	Check status of a run
`get_files_runs`(self, id, run_id)	Check status of a run
`list`(self, \*[, type, author, destination, …])	List Imports
`list_batches`(self, \*[, hidden, limit, …])	List batch imports
`list_files_csv_runs`(self, id, \*[, limit, …])	List runs for the given csv_import
`list_files_csv_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_files_runs`(self, id, \*[, limit, …])	List runs for the given import
`list_files_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`list_projects`(self, id, \*[, hidden])	List the projects an Import belongs to
`list_runs`(self, id)	Get the run history of this import
`list_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`list_shares`(self, id)	List users and groups permissioned on this object
`patch_files_csv`(self, id, \*[, name, …])	Update some attributes of this CSV Import
`post`(self, name, sync_type, is_outbound, \*)	Create a new import configuration
`post_batches`(self, file_ids, schema, table, …)	Upload multiple files to Civis
`post_cancel`(self, id)	Cancel a run
`post_files`(self, schema, name, …[, …])	Initate an import of a tabular file into the platform
`post_files_csv`(self, source, destination, …)	Create a CSV Import
`post_files_csv_runs`(self, id)	Start a run
`post_files_runs`(self, id)	Start a run
`post_runs`(self, id)	Run an import
`post_syncs`(self, id, source, destination, \*)	Create a sync
`put`(self, id, name, sync_type, is_outbound, \*)	Update an import
`put_archive`(self, id, status)	Update the archive status of this object
`put_files_csv`(self, id, source, destination, …)	Replace all attributes of this CSV Import
`put_files_csv_archive`(self, id, status)	Update the archive status of this object
`put_projects`(self, id, project_id)	Add an Import to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object
`put_syncs`(self, id, sync_id, source, …[, …])	Update a sync
`put_syncs_archive`(self, id, sync_id, \*[, …])	Update the archive status of this sync

delete_files_csv_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the csv_import. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_files_runs(self, 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(self, id, project_id)¶

Remove an Import from a project

Parameters:	id : integer The ID of the Import. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, 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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.
name : string

schedule : dict::

scheduled : boolean

If the item 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
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
    - use_without_schema : boolean
        This attribute is no longer available; defaults to false but
        cannot be used.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - spreadsheet_id : string
        The spreadsheet document id.
    - worksheet : string
        The worksheet tab name.
    - worksheet_id : integer
        The worksheet tab id.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.

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.
  
  use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
- google_worksheet : dict::
  
  spreadsheet : string
  
  The spreadsheet document name.
  
  spreadsheet_id : string
  
  The spreadsheet document id.
  
  worksheet : string
  
  The worksheet tab name.
  
  worksheet_id : integer
  
  The worksheet tab id.
advanced_options : dict::
- max_errors : integer
- existing_table_rows : string
- diststyle : 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 index of the column being overridden.
- escaped : boolean
  
  If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
- 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
  
  This parameter is deprecated
- partition_schema_name : string
  
  This parameter is deprecated
- partition_table_name : string
  
  This parameter is deprecated
- partition_table_partition_column_min_name : string
  
  This parameter is deprecated
- partition_table_partition_column_max_name : string
  
  This parameter is deprecated
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
  
  This attribute is no longer available; defaults to true but cannot be used.
- 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 chosen 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. Default is set to “newsprsht”
- sql_query : string
  
  If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
- include_deleted_records : boolean

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

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 item.

archived : string

The archival status of the requested item(s).

get_batches(self, 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 item.

get_files_csv(self, id)¶

Get a CSV Import

Parameters:

id : integer

Returns:

id : integer

The ID for the import.

name : string

The name of the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean

The hidden status of the item.

get_files_csv_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the csv_import.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
csv_import_id : integer: The ID of the csv_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.

get_files_runs(self, 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(self, *, type='DEFAULT', author='DEFAULT', destination='DEFAULT', source='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Imports

Parameters:

type : string, optional: If specified, return imports of these types. It accepts a comma-separated list, possible values are ‘AutoImport’, ‘DbSync’, ‘Salesforce’, ‘GdocImport’.
author : string, optional: If specified, return imports from this author. It accepts a comma-separated list of author ids.
destination : string, optional: If specified, returns imports with one of these destinations. It accepts a comma-separated list of remote host ids.
source : string, optional: If specified, returns imports with one of these sources. It accepts a comma-separated list of remote host ids. ‘DbSync’ must be specified for ‘type’.
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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.
name : string

schedule : dict::

scheduled : boolean

If the item 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 item(s).

list_batches(self, *, 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 items. Defaults to false, returning non-hidden items.
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_csv_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given csv_import

Parameters:

id : integer: The ID of the csv_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.
csv_import_id : integer: The ID of the csv_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_csv_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the csv_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_files_runs(self, 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(self, 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(self, id, *, hidden='DEFAULT')¶

List the projects an Import belongs to

Parameters:

id : integer: The ID of the Import.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_runs(self, 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(self, 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_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_files_csv(self, id, *, name='DEFAULT', source='DEFAULT', destination='DEFAULT', first_row_is_header='DEFAULT', column_delimiter='DEFAULT', escaped='DEFAULT', compression='DEFAULT', existing_table_rows='DEFAULT', max_errors='DEFAULT', table_columns='DEFAULT', loosen_types='DEFAULT', execution='DEFAULT', redshift_destination_options='DEFAULT')¶

Update some attributes of this CSV Import

Parameters:

id : integer

The ID for the import.

name : string, optional

The name of the import.

source : dict, optional::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict, optional::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean, optional

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string, optional

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean, optional

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string, optional

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string, optional

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer, optional

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list, optional::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean, optional

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string, optional

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict, optional::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

Returns:

id : integer

The ID for the import.

name : string

The name of the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean

The hidden status of the item.

post(self, 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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.

schedule : dict, optional::

scheduled : boolean

If the item 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 item.

Returns:

name : string

The name of the import.

sync_type : string

The type of sync to perform; one of Dbsync, AutoImport, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.
name : string

schedule : dict::

scheduled : boolean

If the item 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
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
    - use_without_schema : boolean
        This attribute is no longer available; defaults to false but
        cannot be used.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - spreadsheet_id : string
        The spreadsheet document id.
    - worksheet : string
        The worksheet tab name.
    - worksheet_id : integer
        The worksheet tab id.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.

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.
  
  use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
- google_worksheet : dict::
  
  spreadsheet : string
  
  The spreadsheet document name.
  
  spreadsheet_id : string
  
  The spreadsheet document id.
  
  worksheet : string
  
  The worksheet tab name.
  
  worksheet_id : integer
  
  The worksheet tab id.
advanced_options : dict::
- max_errors : integer
- existing_table_rows : string
- diststyle : 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 index of the column being overridden.
- escaped : boolean
  
  If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
- 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
  
  This parameter is deprecated
- partition_schema_name : string
  
  This parameter is deprecated
- partition_table_name : string
  
  This parameter is deprecated
- partition_table_partition_column_min_name : string
  
  This parameter is deprecated
- partition_table_partition_column_max_name : string
  
  This parameter is deprecated
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
  
  This attribute is no longer available; defaults to true but cannot be used.
- 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 chosen 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. Default is set to “newsprsht”
- sql_query : string
  
  If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
- include_deleted_records : boolean

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

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 item.

archived : string

The archival status of the requested item(s).

post_batches(self, 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 Civis

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 item.

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 item.

post_cancel(self, 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(self, schema, name, remote_host_id, credential_id, *, max_errors='DEFAULT', existing_table_rows='DEFAULT', diststyle='DEFAULT', distkey='DEFAULT', sortkey1='DEFAULT', sortkey2='DEFAULT', column_delimiter='DEFAULT', first_row_is_header='DEFAULT', multipart='DEFAULT', escaped='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”.
diststyle : string, optional: The diststyle to use for the table. One of “even”, “all”, or “key”.
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.
escaped : boolean, optional: If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
hidden : boolean, optional: The hidden status of the item.

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 response.
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 response, 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_csv(self, source, destination, first_row_is_header, *, name='DEFAULT', column_delimiter='DEFAULT', escaped='DEFAULT', compression='DEFAULT', existing_table_rows='DEFAULT', max_errors='DEFAULT', table_columns='DEFAULT', loosen_types='DEFAULT', execution='DEFAULT', redshift_destination_options='DEFAULT', hidden='DEFAULT')¶

Create a CSV Import

Parameters:

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

name : string, optional

The name of the import.

column_delimiter : string, optional

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean, optional

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string, optional

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string, optional

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer, optional

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list, optional::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean, optional

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string, optional

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict, optional::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean, optional

The hidden status of the item.

Returns:

id : integer

The ID for the import.

name : string

The name of the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean

The hidden status of the item.

post_files_csv_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the csv_import.

Returns:

id : integer: The ID of the run.
csv_import_id : integer: The ID of the csv_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_files_runs(self, 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(self, 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(self, 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
database_table : dict::
- schema : string
  
  The database schema name.
- table : string
  
  The database table name.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
file : dict
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.
salesforce : dict::
- object_name : string
  
  The Salesforce object name.

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.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.

advanced_options : dict, optional::

max_errors : integer
existing_table_rows : string
diststyle : 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 index of the column being overridden.
escaped : boolean

If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
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

This parameter is deprecated
partition_schema_name : string

This parameter is deprecated
partition_table_name : string

This parameter is deprecated
partition_table_partition_column_min_name : string

This parameter is deprecated
partition_table_partition_column_max_name : string

This parameter is deprecated
last_modified_column : string
mysql_catalog_matches_schema : boolean

This attribute is no longer available; defaults to true but cannot be used.
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 chosen 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. Default is set to “newsprsht”
sql_query : string

If you are doing a Google Sheet export, this is your SQL query.
contact_lists : string
soql_query : string
include_deleted_records : boolean

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
database_table : dict::
- schema : string
  
  The database schema name.
- table : string
  
  The database table name.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
file : dict::
- id : integer
  
  The file id.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.
salesforce : dict::
- object_name : string
  
  The Salesforce object name.

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.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.

advanced_options : dict::

max_errors : integer
existing_table_rows : string
diststyle : 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 index of the column being overridden.
escaped : boolean

If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
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

This parameter is deprecated
partition_schema_name : string

This parameter is deprecated
partition_table_name : string

This parameter is deprecated
partition_table_partition_column_min_name : string

This parameter is deprecated
partition_table_partition_column_max_name : string

This parameter is deprecated
last_modified_column : string
mysql_catalog_matches_schema : boolean

This attribute is no longer available; defaults to true but cannot be used.
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 chosen 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. Default is set to “newsprsht”
sql_query : string

If you are doing a Google Sheet export, this is your SQL query.
contact_lists : string
soql_query : string
include_deleted_records : boolean

put(self, 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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.

schedule : dict, optional::

scheduled : boolean

If the item 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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.
name : string

schedule : dict::

scheduled : boolean

If the item 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
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
    - use_without_schema : boolean
        This attribute is no longer available; defaults to false but
        cannot be used.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - spreadsheet_id : string
        The spreadsheet document id.
    - worksheet : string
        The worksheet tab name.
    - worksheet_id : integer
        The worksheet tab id.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.

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.
  
  use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
- google_worksheet : dict::
  
  spreadsheet : string
  
  The spreadsheet document name.
  
  spreadsheet_id : string
  
  The spreadsheet document id.
  
  worksheet : string
  
  The worksheet tab name.
  
  worksheet_id : integer
  
  The worksheet tab id.
advanced_options : dict::
- max_errors : integer
- existing_table_rows : string
- diststyle : 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 index of the column being overridden.
- escaped : boolean
  
  If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
- 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
  
  This parameter is deprecated
- partition_schema_name : string
  
  This parameter is deprecated
- partition_table_name : string
  
  This parameter is deprecated
- partition_table_partition_column_min_name : string
  
  This parameter is deprecated
- partition_table_partition_column_max_name : string
  
  This parameter is deprecated
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
  
  This attribute is no longer available; defaults to true but cannot be used.
- 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 chosen 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. Default is set to “newsprsht”
- sql_query : string
  
  If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
- include_deleted_records : boolean

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

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 item.

archived : string

The archival status of the requested item(s).

put_archive(self, 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, 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key 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. For DB Syncs, the first element is an SSL private key credential id, and the second element is the corresponding public key credential id.
name : string

schedule : dict::

scheduled : boolean

If the item 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
- database_table : dict::
    - schema : string
        The database schema name.
    - table : string
        The database table name.
    - use_without_schema : boolean
        This attribute is no longer available; defaults to false but
        cannot be used.
- file : dict::
    - id : integer
        The file id.
- google_worksheet : dict::
    - spreadsheet : string
        The spreadsheet document name.
    - spreadsheet_id : string
        The spreadsheet document id.
    - worksheet : string
        The worksheet tab name.
    - worksheet_id : integer
        The worksheet tab id.
- salesforce : dict::
    - object_name : string
        The Salesforce object name.

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.
  
  use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
- google_worksheet : dict::
  
  spreadsheet : string
  
  The spreadsheet document name.
  
  spreadsheet_id : string
  
  The spreadsheet document id.
  
  worksheet : string
  
  The worksheet tab name.
  
  worksheet_id : integer
  
  The worksheet tab id.
advanced_options : dict::
- max_errors : integer
- existing_table_rows : string
- diststyle : 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 index of the column being overridden.
- escaped : boolean
  
  If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
- 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
  
  This parameter is deprecated
- partition_schema_name : string
  
  This parameter is deprecated
- partition_table_name : string
  
  This parameter is deprecated
- partition_table_partition_column_min_name : string
  
  This parameter is deprecated
- partition_table_partition_column_max_name : string
  
  This parameter is deprecated
- last_modified_column : string
- mysql_catalog_matches_schema : boolean
  
  This attribute is no longer available; defaults to true but cannot be used.
- 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 chosen 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. Default is set to “newsprsht”
- sql_query : string
  
  If you are doing a Google Sheet export, this is your SQL query.
- contact_lists : string
- soql_query : string
- include_deleted_records : boolean

state : string

created_at : string/date-time

updated_at : string/date-time

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

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 item.

archived : string

The archival status of the requested item(s).

put_files_csv(self, id, source, destination, first_row_is_header, *, name='DEFAULT', column_delimiter='DEFAULT', escaped='DEFAULT', compression='DEFAULT', existing_table_rows='DEFAULT', max_errors='DEFAULT', table_columns='DEFAULT', loosen_types='DEFAULT', execution='DEFAULT', redshift_destination_options='DEFAULT')¶

Replace all attributes of this CSV Import

Parameters:

id : integer

The ID for the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

name : string, optional

The name of the import.

column_delimiter : string, optional

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean, optional

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string, optional

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string, optional

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer, optional

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list, optional::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean, optional

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string, optional

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict, optional::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

Returns:

id : integer

The ID for the import.

name : string

The name of the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean

The hidden status of the item.

put_files_csv_archive(self, 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 import.

name : string

The name of the import.

source : dict::

file_ids : list

The file ID(s) to import, if importing Civis file(s).
storage_path : dict::
- storage_host_id : integer
  
  The ID of the source storage host.
- credential_id : integer
  
  The ID of the credentials for the source storage host.
- file_paths : list
  
  The file or directory path(s) within the bucket from which to import. E.g. the file_path for “s3://mybucket/files/all/” would be “/files/all/”If specifying a directory path, the job will import every file found under that path. All files must have the same column layout and file format (e.g., compression, columnDelimiter, etc.).

destination : dict::

schema : string

The destination schema name.
table : string

The destination table name.
remote_host_id : integer

The ID of the destination database host.
credential_id : integer

The ID of the credentials for the destination database.
primary_keys : list

A list of column(s) which together uniquely identify a row in the destination table.These columns must not contain NULL values. If the import mode is “upsert”, this field is required;see the Civis Helpdesk article on “Advanced CSV Imports via the Civis API” for more information.
last_modified_keys : list

A list of the columns indicating a record has been updated.If the destination table does not exist, and the import mode is “upsert”, this field is required.

first_row_is_header : boolean

A boolean value indicating whether or not the first row of the source file is a header row.

column_delimiter : string

The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. Defaults to “comma”.

escaped : boolean

A boolean value indicating whether or not the source file has quotes escaped with a backslash.Defaults to false.

compression : string

The type of compression of the source file. Valid arguments are “gzip” and “none”. Defaults to “none”.

existing_table_rows : string

The behavior if a destination table with the requested name already exists. One of “fail”, “truncate”, “append”, “drop”, or “upsert”.Defaults to “fail”.

max_errors : integer

The maximum number of rows with errors to ignore before failing. This option is not supported for Postgres databases.

table_columns : list::

An array of hashes corresponding to the columns in the order they appear in the source file. Each hash should have keys for database column “name” and “sqlType”.This parameter is required if the table does not exist, the table is being dropped, or the columns in the source file do not appear in the same order as in the destination table.The “sqlType” key is not required when appending to an existing table. - name : string

The column name.

sql_type : string

The SQL type of the column.

loosen_types : boolean

If true, SQL types with precisions/lengths will have these values increased to accommodate data growth in future loads. Type loosening only occurs on table creation. Defaults to false.

execution : string

In upsert mode, controls the movement of data in upsert mode. If set to “delayed”, the data will be moved after a brief delay. If set to “immediate”, the data will be moved immediately. In non-upsert modes, controls the speed at which detailed column stats appear in the data catalogue. Defaults to “delayed”, to accommodate concurrent upserts to the same table and speedier non-upsert imports.

redshift_destination_options : dict::

diststyle : string

The diststyle to use for the table. One of “even”, “all”, or “key”.
distkey : string

Distkey for this table in Redshift
sortkeys : list

Sortkeys for this table in Redshift. Please provide a maximum of two.

hidden : boolean

The hidden status of the item.

put_projects(self, id, project_id)¶

Add an Import to a project

Parameters:	id : integer The ID of the Import. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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(self, 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
database_table : dict::
- schema : string
  
  The database schema name.
- table : string
  
  The database table name.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
file : dict
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.
salesforce : dict::
- object_name : string
  
  The Salesforce object name.

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.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.

advanced_options : dict, optional::

max_errors : integer
existing_table_rows : string
diststyle : 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 index of the column being overridden.
escaped : boolean

If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
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

This parameter is deprecated
partition_schema_name : string

This parameter is deprecated
partition_table_name : string

This parameter is deprecated
partition_table_partition_column_min_name : string

This parameter is deprecated
partition_table_partition_column_max_name : string

This parameter is deprecated
last_modified_column : string
mysql_catalog_matches_schema : boolean

This attribute is no longer available; defaults to true but cannot be used.
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 chosen 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. Default is set to “newsprsht”
sql_query : string

If you are doing a Google Sheet export, this is your SQL query.
contact_lists : string
soql_query : string
include_deleted_records : boolean

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
database_table : dict::
- schema : string
  
  The database schema name.
- table : string
  
  The database table name.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
file : dict::
- id : integer
  
  The file id.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.
salesforce : dict::
- object_name : string
  
  The Salesforce object name.

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.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.

advanced_options : dict::

max_errors : integer
existing_table_rows : string
diststyle : 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 index of the column being overridden.
escaped : boolean

If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
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

This parameter is deprecated
partition_schema_name : string

This parameter is deprecated
partition_table_name : string

This parameter is deprecated
partition_table_partition_column_min_name : string

This parameter is deprecated
partition_table_partition_column_max_name : string

This parameter is deprecated
last_modified_column : string
mysql_catalog_matches_schema : boolean

This attribute is no longer available; defaults to true but cannot be used.
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 chosen 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. Default is set to “newsprsht”
sql_query : string

If you are doing a Google Sheet export, this is your SQL query.
contact_lists : string
soql_query : string
include_deleted_records : boolean

put_syncs_archive(self, 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
database_table : dict::
- schema : string
  
  The database schema name.
- table : string
  
  The database table name.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
file : dict::
- id : integer
  
  The file id.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.
salesforce : dict::
- object_name : string
  
  The Salesforce object name.

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.
- use_without_schema : boolean
  
  This attribute is no longer available; defaults to false but cannot be used.
google_worksheet : dict::
- spreadsheet : string
  
  The spreadsheet document name.
- spreadsheet_id : string
  
  The spreadsheet document id.
- worksheet : string
  
  The worksheet tab name.
- worksheet_id : integer
  
  The worksheet tab id.

advanced_options : dict::

max_errors : integer
existing_table_rows : string
diststyle : 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 index of the column being overridden.
escaped : boolean

If true, escape quotes with a backslash; otherwise, escape quotes by double-quoting. Defaults to false.
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

This parameter is deprecated
partition_schema_name : string

This parameter is deprecated
partition_table_name : string

This parameter is deprecated
partition_table_partition_column_min_name : string

This parameter is deprecated
partition_table_partition_column_max_name : string

This parameter is deprecated
last_modified_column : string
mysql_catalog_matches_schema : boolean

This attribute is no longer available; defaults to true but cannot be used.
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 chosen 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. Default is set to “newsprsht”
sql_query : string

If you are doing a Google Sheet export, this is your SQL query.
contact_lists : string
soql_query : string
include_deleted_records : boolean

Jobs¶

class Jobs(session_kwargs, client, return_type='civis')¶

Methods

`delete_projects`(self, id, project_id)	Remove a Job from a project
`delete_runs`(self, id, run_id)	Cancel a run
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Show basic job info
`get_runs`(self, id, run_id)	Check status of a job
`list`(self, \*[, state, type, q, permission, …])	List Jobs
`list_children`(self, id)	Show nested tree of children that this job triggers
`list_parents`(self, id)	Show chain of parents as a list that this job triggers from
`list_projects`(self, id, \*[, hidden])	List the projects a Job belongs to
`list_runs`(self, id, \*[, limit, page_num, …])	List runs for the given job
`list_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`list_runs_outputs`(self, id, run_id, \*[, …])	List the outputs for a run
`list_shares`(self, id)	List users and groups permissioned on this object
`list_workflows`(self, id, \*[, archived])	List the workflows a job belongs to
`post_runs`(self, id)	Run a job
`post_trigger_email`(self, id)	Generate and retrieve trigger email address
`put_archive`(self, id, status)	Update the archive status of this object
`put_projects`(self, id, project_id)	Add a Job to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_projects(self, id, project_id)¶

Remove a Job from a project

Parameters:	id : integer The ID of the Job. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the Job. run_id : integer The ID of the Run.
Returns:	None Response code 202: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Show basic job info

Parameters:

id : integer: The ID for this job.

Returns:

id : integer

name : string

type : string

from_template_id : integer

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 item.

archived : string

The archival status of the requested item(s).

success_email_subject : string

success_email_body : string

running_as_user : string

run_by_user : string

schedule : dict::

scheduled : boolean

If the item 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.

get_runs(self, 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(self, *, state='DEFAULT', type='DEFAULT', q='DEFAULT', permission='DEFAULT', scheduled='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Jobs

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.
scheduled : boolean, optional: If the item is scheduled.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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

from_template_id : integer

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 item(s).

schedule : dict::

scheduled : boolean

If the item 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_children(self, 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

from_template_id : integer

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(self, 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

from_template_id : integer

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 item.

archived : string

The archival status of the requested item(s).

success_email_subject : string

success_email_body : string

running_as_user : string

run_by_user : string

schedule : dict::

scheduled : boolean

If the item 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_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Job belongs to

Parameters:

id : integer: The ID of the Job.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given job

Parameters:

id : integer: The ID for this job.
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
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(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the job. 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_runs_outputs(self, 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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_workflows(self, id, *, archived='DEFAULT')¶

List the workflows a job belongs to

Parameters:

id : integer
archived : string, optional: The archival status of the requested item(s).

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

valid : boolean

The validity of the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

archived : string

The archival status of the requested item(s).

created_at : string/time

updated_at : string/time

post_runs(self, 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(self, 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_archive(self, 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

name : string

type : string

from_template_id : integer

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 item.

archived : string

The archival status of the requested item(s).

success_email_subject : string

success_email_body : string

running_as_user : string

run_by_user : string

schedule : dict::

scheduled : boolean

If the item 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.

put_projects(self, id, project_id)¶

Add a Job to a project

Parameters:	id : integer The ID of the Job. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Json_Values¶

civis.resources._resources.Json_Values¶: alias of civis.resources._resources.JsonValues

Match_Targets¶

civis.resources._resources.Match_Targets¶: alias of civis.resources._resources.MatchTargets

Media¶

class Media(session_kwargs, client, return_type='civis')¶

Methods

`delete_optimizations_runs`(self, id, run_id)	Cancel a run
`delete_optimizations_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_optimizations_shares_users`(self, id, …)	Revoke the permissions a user has on this object
`delete_ratecards_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_ratecards_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_spot_orders_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_spot_orders_shares_users`(self, id, …)	Revoke the permissions a user has on this object
`get_optimizations`(self, id)	Show a single optimization
`get_optimizations_runs`(self, id, run_id)	Check status of a run
`get_ratecards`(self, id)	Get a Ratecard
`get_spot_orders`(self, id)	Show a single spot order
`list_dmas`(self, \*[, name, number])	List all Designated Market Areas
`list_optimizations`(self, \*[, archived, …])	List all optimizations
`list_optimizations_runs`(self, id, \*[, …])	List runs for the given optimization
`list_optimizations_runs_logs`(self, id, …)	Get the logs for a run
`list_optimizations_shares`(self, id)	List users and groups permissioned on this object
`list_ratecards`(self, \*[, archived, …])	List all ratecards
`list_ratecards_shares`(self, id)	List users and groups permissioned on this object
`list_spot_orders`(self, \*[, id, archived])	List all spot orders
`list_spot_orders_shares`(self, id)	List users and groups permissioned on this object
`list_targets`(self, \*[, name, identifier, …])	List all Media Targets
`patch_optimizations`(self, id, \*[, name, …])	Edit an existing optimization
`patch_ratecards`(self, id, \*[, filename, …])	Update some attributes of this Ratecard
`post_optimizations`(self, runs, \*[, name, …])	Create a new optimization
`post_optimizations_clone`(self, id)	Clone an existing optimization
`post_optimizations_runs`(self, id)	Start a run
`post_ratecards`(self, filename, start_on, …)	Create a Ratecard
`post_spot_orders`(self, \*[, body])	Create a spot order
`put_optimizations_archive`(self, id, status)	Update the archive status of this object
`put_optimizations_shares_groups`(self, id, …)	Set the permissions groups has on this object
`put_optimizations_shares_users`(self, id, …)	Set the permissions users have on this object
`put_ratecards`(self, id, filename, start_on, …)	Replace all attributes of this Ratecard
`put_ratecards_archive`(self, id, status)	Update the archive status of this object
`put_ratecards_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_ratecards_shares_users`(self, id, …[, …])	Set the permissions users have on this object
`put_spot_orders`(self, id, \*[, body])	Edit the specified spot order
`put_spot_orders_archive`(self, id, status)	Update the archive status of this object
`put_spot_orders_shares_groups`(self, id, …)	Set the permissions groups has on this object
`put_spot_orders_shares_users`(self, id, …)	Set the permissions users have on this object

delete_optimizations_runs(self, 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

delete_optimizations_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_optimizations_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_ratecards_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_ratecards_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_spot_orders_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_spot_orders_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get_optimizations(self, 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 item(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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

get_optimizations_runs(self, 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_ratecards(self, id)¶

Get a Ratecard

Parameters:	id : integer
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. archived : string The archival status of the requested item(s).

get_spot_orders(self, 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 item(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(self, *, 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(self, *, 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 item(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 item(s).

list_optimizations_runs(self, 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(self, 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_optimizations_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, *, archived='DEFAULT', filename='DEFAULT', dma_number='DEFAULT')¶

List all ratecards

Parameters:

archived : string, optional: The archival status of the requested item(s).
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.
archived : string: The archival status of the requested item(s).

list_ratecards_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_spot_orders(self, *, 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 item(s).
Returns:	id : integer The ID for the spot order. archived : string The archival status of the requested item(s).

list_spot_orders_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, *, 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(self, id, *, name='DEFAULT', runs='DEFAULT', programs='DEFAULT', networks='DEFAULT', exclude_programs='DEFAULT', exclude_networks='DEFAULT', time_slot_percentages='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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list, optional

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list, optional

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean, optional

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean, optional

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict, optional

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

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 item(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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

patch_ratecards(self, id, *, filename='DEFAULT', start_on='DEFAULT', end_on='DEFAULT', dma_number='DEFAULT')¶

Update some attributes of this Ratecard

Parameters:	id : integer The ratecard ID. filename : string, optional Name of the ratecard file. start_on : string/date, optional First day to which the ratecard applies. end_on : string/date, optional Last day to which the ratecard applies. dma_number : integer, optional Number of the DMA associated with the ratecard.
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. archived : string The archival status of the requested item(s).

post_optimizations(self, runs, *, name='DEFAULT', programs='DEFAULT', networks='DEFAULT', exclude_programs='DEFAULT', exclude_networks='DEFAULT', time_slot_percentages='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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

name : string, optional

The name of the optimization.

programs : list, optional

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list, optional

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean, optional

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean, optional

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict, optional

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

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 item(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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

post_optimizations_clone(self, 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 item(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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

post_optimizations_runs(self, 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_ratecards(self, filename, start_on, end_on, dma_number)¶

Create a Ratecard

Parameters:	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.
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. archived : string The archival status of the requested item(s).

post_spot_orders(self, *, 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 item(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(self, 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 item(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.
force_cpm : boolean

Whether to force optimization to use CPM data even if partition data is available.
reach_alpha : number/float

A tuning parameter used to adjust RF.
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 : number/float
  
  The maximum frequency for these targets.

programs : list

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networks : list

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programs : boolean

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networks : boolean

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentages : dict

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

put_optimizations_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_optimizations_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_ratecards(self, id, filename, start_on, end_on, dma_number)¶

Replace all attributes of this Ratecard

Parameters:	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.
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. archived : string The archival status of the requested item(s).

put_ratecards_archive(self, 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 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. archived : string The archival status of the requested item(s).

put_ratecards_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_ratecards_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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(self, 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 item(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(self, 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 item(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_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_spot_orders_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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, client, return_type='civis')¶

Methods

`delete_builds`(self, id, build_id)	Cancel a build
`delete_projects`(self, id, project_id)	Remove a Model from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Retrieve model configuration
`get_builds`(self, id, build_id)	Check status of a build
`list`(self, \*[, model_name, …])	List
`list_builds`(self, id, \*[, limit, page_num, …])	List builds for the given model
`list_builds_logs`(self, id, build_id, \*[, …])	Get the logs for a build
`list_projects`(self, id, \*[, hidden])	List the projects a Model belongs to
`list_schedules`(self, id)	Show the model build schedule
`list_shares`(self, id)	List users and groups permissioned on this object
`list_types`(self)	List all available model types
`put_archive`(self, id, status)	Update the archive status of this object
`put_projects`(self, id, project_id)	Add a Model to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_builds(self, 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(self, id, project_id)¶

Remove a Model from a project

Parameters:	id : integer The ID of the Model. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, 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 item 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 item.

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 item 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 item(s).

get_builds(self, 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(self, *, 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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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 item 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 item(s).

list_builds(self, 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(self, 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(self, id, *, hidden='DEFAULT')¶

List the projects a Model belongs to

Parameters:

id : integer: The ID of the Model.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_schedules(self, 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 item 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_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self)¶

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.

put_archive(self, 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 item 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 item.

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 item 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 item(s).

put_projects(self, id, project_id)¶

Add a Model to a project

Parameters:	id : integer The ID of the Model. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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, client, return_type='civis')¶

Methods

`delete_deployments`(self, notebook_id, …)	Delete a Notebook deployment
`delete_projects`(self, id, project_id)	Remove a Notebook from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get a Notebook
`get_deployments`(self, notebook_id, deployment_id)	Get details about a Notebook deployment
`get_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`list`(self, \*[, hidden, archived, author, …])	List Notebooks
`list_deployments`(self, notebook_id, \*[, …])	List deployments for a Notebook
`list_deployments_logs`(self, id, …[, …])	Get the logs for a Notebook deployment
`list_git`(self, id)	Get the git metadata attached to an item
`list_git_commits`(self, id)	Get the git commits for an item
`list_projects`(self, id, \*[, hidden])	List the projects a Notebook belongs to
`list_shares`(self, id)	List users and groups permissioned on this object
`list_update_links`(self, id)	Get URLs to update notebook
`patch`(self, id, \*[, name, language, …])	Update some attributes of this Notebook
`patch_git`(self, id, \*[, git_ref, …])	Update an attached git file
`post`(self, \*[, name, language, …])	Create a Notebook
`post_clone`(self, id)	Clone this Notebook
`post_deployments`(self, notebook_id, \*[, …])	Deploy a Notebook
`post_git_commits`(self, id, content, message, …)	Commit and push a new version of the file
`put`(self, id, \*[, name, language, …])	Replace all attributes of this Notebook
`put_archive`(self, id, status)	Update the archive status of this object
`put_git`(self, id, \*[, git_ref, git_branch, …])	Attach an item to a file in a git repo
`put_projects`(self, id, project_id)	Add a Notebook to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_deployments(self, 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(self, id, project_id)¶

Remove a Notebook from a project

Parameters:	id : integer The ID of the Notebook. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, 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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

get_deployments(self, 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: A signed URL for viewing the deployed item.
instance_type : string: The EC2 instance type requested for the deployment.
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
notebook_id : integer: The ID of owning Notebook

get_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

list(self, *, 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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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_image_tag : string

The tag of the docker image to pull from DockerHub (default: latest).
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

archived : string

The archival status of the requested item(s).

list_deployments(self, notebook_id, *, deployment_id='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List deployments for a Notebook

Parameters:

notebook_id : integer: The ID of the owning Notebook
deployment_id : integer, optional: The ID for this deployment
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to created_at. Must be one of: created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

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).
instance_type : string: The EC2 instance type requested for the deployment.
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
notebook_id : integer: The ID of owning Notebook

list_deployments_logs(self, id, deployment_id, *, start_at='DEFAULT', end_at='DEFAULT', limit='DEFAULT')¶

Get the logs for a Notebook deployment

Parameters:	id : integer The ID of the owning Notebook. deployment_id : integer The ID for this deployment. start_at : string, optional Log entries with a lower timestamp will be omitted. end_at : string, optional Log entries with a higher timestamp will be omitted. limit : integer, optional The maximum number of log messages to return. Default of 10000.
Returns:	message : string The log message. stream : string The stream of the log. One of “stdout”, “stderr”. created_at : string/date-time The time the log was created. source : string The source of the log. One of “system”, “user”.

list_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Notebook belongs to

Parameters:

id : integer: The ID of the Notebook.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_update_links(self, id)¶

Get URLs to update notebook

Parameters:	id : integer
Returns:	update_url : string Time-limited URL to PUT new contents of the .ipynb file for this notebook. update_preview_url : string Time-limited URL to PUT new contents of the .htm preview file for this notebook.

patch(self, id, *, name='DEFAULT', language='DEFAULT', description='DEFAULT', file_id='DEFAULT', requirements_file_id='DEFAULT', requirements='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', environment_variables='DEFAULT', idle_timeout='DEFAULT', partition_label='DEFAULT', git_repo_url='DEFAULT', git_ref='DEFAULT', git_path='DEFAULT')¶

Update some attributes of this Notebook

Parameters:

id : integer: The ID for this notebook.
name : string, optional: The name of this notebook.
language : string, optional: The kernel language of this notebook.
description : string, optional: The description of this notebook.
file_id : string, optional: The file ID for the S3 file containing the .ipynb file.
requirements_file_id : string, optional: The file ID for the S3 file containing the requirements.txt file.
requirements : string, optional: The requirements txt file.
docker_image_name : string, optional: The name of the docker image to pull from DockerHub.
docker_image_tag : string, optional: The tag of the docker image to pull from DockerHub (default: latest).
instance_type : string, optional: The EC2 instance type to deploy to.
memory : integer, optional: The amount of memory allocated to the notebook.
cpu : integer, optional: The amount of cpu allocated to the the notebook.
credentials : list, optional: A list of credential IDs to pass to the notebook.
environment_variables : dict, optional: Environment variables to be passed into the Notebook.
idle_timeout : integer, optional: How long the notebook will stay alive without any kernel activity.
partition_label : string, optional: The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.
git_repo_url : string, optional: The url of the git repository
git_ref : string, optional: The git reference if git repo is specified
git_path : string, optional: The path to the .ipynb file in the git repo that will be started up on notebook launch

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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

patch_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

post(self, *, name='DEFAULT', language='DEFAULT', description='DEFAULT', file_id='DEFAULT', requirements_file_id='DEFAULT', requirements='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', environment_variables='DEFAULT', idle_timeout='DEFAULT', partition_label='DEFAULT', git_repo_url='DEFAULT', git_ref='DEFAULT', git_path='DEFAULT', hidden='DEFAULT')¶

Create a Notebook

Parameters:

name : string, optional: The name of this notebook.
language : string, optional: The kernel language of this notebook.
description : string, optional: The description of this notebook.
file_id : string, optional: The file ID for the S3 file containing the .ipynb file.
requirements_file_id : string, optional: The file ID for the S3 file containing the requirements.txt file.
requirements : string, optional: The requirements txt file.
docker_image_name : string, optional: The name of the docker image to pull from DockerHub.
docker_image_tag : string, optional: The tag of the docker image to pull from DockerHub (default: latest).
instance_type : string, optional: The EC2 instance type to deploy to.
memory : integer, optional: The amount of memory allocated to the notebook.
cpu : integer, optional: The amount of cpu allocated to the the notebook.
credentials : list, optional: A list of credential IDs to pass to the notebook.
environment_variables : dict, optional: Environment variables to be passed into the Notebook.
idle_timeout : integer, optional: How long the notebook will stay alive without any kernel activity.
partition_label : string, optional: The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.
git_repo_url : string, optional: The url of the git repository
git_ref : string, optional: The git reference if git repo is specified
git_path : string, optional: The path to the .ipynb file in the git repo that will be started up on notebook launch
hidden : boolean, optional: The hidden status of the item.

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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

post_clone(self, id)¶

Clone this 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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

post_deployments(self, notebook_id, *, deployment_id='DEFAULT')¶

Deploy a Notebook

Parameters:

notebook_id : integer: The ID of the owning Notebook
deployment_id : integer, optional: 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: A signed URL for viewing the deployed item.
instance_type : string: The EC2 instance type requested for the deployment.
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
notebook_id : integer: The ID of owning Notebook

post_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

put(self, id, *, name='DEFAULT', language='DEFAULT', description='DEFAULT', file_id='DEFAULT', requirements_file_id='DEFAULT', requirements='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', environment_variables='DEFAULT', idle_timeout='DEFAULT', partition_label='DEFAULT', git_repo_url='DEFAULT', git_ref='DEFAULT', git_path='DEFAULT')¶

Replace all attributes of this Notebook

Parameters:

id : integer: The ID for this notebook.
name : string, optional: The name of this notebook.
language : string, optional: The kernel language of this notebook.
description : string, optional: The description of this notebook.
file_id : string, optional: The file ID for the S3 file containing the .ipynb file.
requirements_file_id : string, optional: The file ID for the S3 file containing the requirements.txt file.
requirements : string, optional: The requirements txt file.
docker_image_name : string, optional: The name of the docker image to pull from DockerHub.
docker_image_tag : string, optional: The tag of the docker image to pull from DockerHub (default: latest).
instance_type : string, optional: The EC2 instance type to deploy to.
memory : integer, optional: The amount of memory allocated to the notebook.
cpu : integer, optional: The amount of cpu allocated to the the notebook.
credentials : list, optional: A list of credential IDs to pass to the notebook.
environment_variables : dict, optional: Environment variables to be passed into the Notebook.
idle_timeout : integer, optional: How long the notebook will stay alive without any kernel activity.
partition_label : string, optional: The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.
git_repo_url : string, optional: The url of the git repository
git_ref : string, optional: The git reference if git repo is specified
git_path : string, optional: The path to the .ipynb file in the git repo that will be started up on notebook launch

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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

put_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID for this 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).

instance_type : string

The EC2 instance type to deploy to.

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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
notebook_id : integer

The ID of owning Notebook

credentials : list

A list of credential IDs to pass to the notebook.

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.

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

git_repo_id : integer

The ID of the git repository.

git_repo_url : string

The url of the git repository

git_ref : string

The git reference if git repo is specified

git_path : string

The path to the .ipynb file in the git repo that will be started up on notebook launch

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

put_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_projects(self, id, project_id)¶

Add a Notebook to a project

Parameters:	id : integer The ID of the Notebook. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Notifications¶

class Notifications(session_kwargs, client, return_type='civis')¶

Methods

list(self, \*[, last_event_id, r, mock]) Receive a stream of notifications as they come in

list(self, *, last_event_id='DEFAULT', r='DEFAULT', mock='DEFAULT')¶

Receive a stream of notifications as they come in

Parameters:	last_event_id : string, optional allows browser to keep track of last event fired r : string, optional specifies retry/reconnect timeout mock : string, optional used for testing
Returns:	None Response code 200: success

Ontology¶

class Ontology(session_kwargs, client, return_type='civis')¶

Methods

list(self, \*[, subset]) List the ontology of column names Civis uses

list(self, *, subset='DEFAULT')¶

List the ontology of column names Civis uses

Parameters:	subset : string, optional A subset of fields to return.
Returns:	key : string title : string desc : string A description of this field. aliases : list

Predictions¶

class Predictions(session_kwargs, client, return_type='civis')¶

Methods

`get`(self, id)	Show the specified prediction
`list`(self, \*[, model_id])	List predictions
`list_schedules`(self, id)	Show the prediction schedule

get(self, id)¶

Show the specified prediction

Parameters:

id : integer: The ID of the prediction.

Returns:

id : integer

The ID of the prediction.

model_id : integer

The ID of the model used for this prediction.

scored_table_id : integer

The ID of the source table for this prediction.

scored_table_name : string

The name of the source table for this prediction.

output_table_name : string

The name of the output table for this prediction.

state : string

The state of the last run of this prediction.

error : string

The error, if any, of the last run of this prediction.

started_at : string/date-time

The start time of the last run of this prediction.

finished_at : string/date-time

The end time of the last run of this prediction.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

scored_tables : list::

An array of created prediction tables. - id : integer

The ID of the table with created predictions.

schema : string

The schema of table with created predictions.
name : string

The name of table with created predictions.
created_at : string/date-time

The time when the table with created predictions was created.
score_stats : list::
An array of metrics on the created predictions. - score_name : string

The name of the score.
- histogram : list
  
  The histogram of the distribution of scores.
- avg_score : number/float
  
  The average score.
- min_score : number/float
  
  The minimum score.
- max_score : number/float
  
  The maximum score.

schedule : dict::

scheduled : boolean

If the item is scheduled.
scheduled_days : list

Day based on numeric value starting at 0 for Sunday.
scheduled_hours : list

Hours of the day it is scheduled on.
scheduled_minutes : list

Minutes of the day it is scheduled on.
scheduled_runs_per_hour : integer

Alternative to scheduled minutes, number of times to run per hour.

limiting_sql : string

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

primary_key : list

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

list(self, *, model_id='DEFAULT')¶

List predictions

Parameters:

model_id : integer, optional: If specified, only return predictions associated with this model ID.

Returns:

id : integer

The ID of the prediction.

model_id : integer

The ID of the model used for this prediction.

scored_table_id : integer

The ID of the source table for this prediction.

scored_table_name : string

The name of the source table for this prediction.

output_table_name : string

The name of the output table for this prediction.

state : string

The state of the last run of this prediction.

error : string

The error, if any, of the last run of this prediction.

started_at : string/date-time

The start time of the last run of this prediction.

finished_at : string/date-time

The end time of the last run of this prediction.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

list_schedules(self, id)¶

Show the prediction schedule

Parameters:

id : integer: ID of the prediction associated with this schedule.

Returns:

id : integer

ID of the prediction associated with this schedule.

schedule : dict::

scheduled : boolean

If the item is scheduled.
scheduled_days : list

Day based on numeric value starting at 0 for Sunday.
scheduled_hours : list

Hours of the day it is scheduled on.
scheduled_minutes : list

Minutes of the day it is scheduled on.
scheduled_runs_per_hour : integer

Alternative to scheduled minutes, number of times to run per hour.

score_on_model_build : boolean

Whether the prediction will run after a rebuild of the associated model.

Projects¶

class Projects(session_kwargs, client, return_type='civis')¶

Methods

`delete_parent_projects`(self, id, …)	Remove an item from a Parent Project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, project_id)	Get a detailed view of a project and the objects in it
`list`(self, \*[, author, permission, hidden, …])	List projects
`list_parent_projects`(self, id, \*[, hidden])	List the Parent Projects an item belongs to
`list_shares`(self, id)	List users and groups permissioned on this object
`post`(self, name, description, \*[, note, hidden])	Create a project
`put`(self, project_id, \*[, name, …])	Update a project
`put_archive`(self, id, status)	Update the archive status of this object
`put_parent_projects`(self, id, parent_project_id)	Add an item to a Parent Project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_parent_projects(self, id, parent_project_id)¶

Remove an item from a Parent Project

Parameters:	id : integer The ID of the item. parent_project_id : integer The ID of the Parent Project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, project_id)¶

Get a detailed view of a project and the objects in it

Parameters:

project_id : integer

Returns:

id : integer

The ID for this project.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

name : string

The name of this project.

description : string

A description of the project.

users : list::

Users who can see the project. - id : integer

The ID of this user.

name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

tables : list::

schema : string
name : string
row_count : integer
column_count : integer
created_at : string/time
updated_at : string/time

surveys : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time

scripts : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

imports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

exports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

models : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

notebooks : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

services : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

workflows : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string
last_execution : dict::
- state : string
- updated_at : string/time

reports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

script_templates : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string

files : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
file_name : string
file_size : integer
expired : boolean

enhancements : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
last_run : dict::
- state : string
- updated_at : string/time

projects : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
description : string

all_objects : list::

project_id : integer
object_id : integer
object_type : string
fco_type : string
sub_type : string
name : string
icon : string
author : string
updated_at : string/time
archived : string

The archival status of the requested item(s).
hidden : boolean

The hidden status of the item.

note : string

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

parent_project : dict::

id : integer

The parent project’s ID.
name : integer

The parent project’s name.

list(self, *, author='DEFAULT', permission='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List projects

Parameters:

author : string, optional: If specified, return projects owned by this author. It accepts a comma- separated list of author ids.
permission : string, optional: A permissions string, one of “read”, “write”, or “manage”. Lists only projects for which the current user has that permission.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(s).
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 1000.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for this project.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

name : string

The name of this project.

description : string

A description of the project.

users : list::

Users who can see the project. - id : integer

The ID of this user.

name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

archived : string

The archival status of the requested item(s).

list_parent_projects(self, id, *, hidden='DEFAULT')¶

List the Parent Projects an item belongs to

Parameters:

id : integer: The ID of the item.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, name, description, *, note='DEFAULT', hidden='DEFAULT')¶

Create a project

Parameters:

name : string: The name of this project.
description : string: A description of the project.
note : string, optional: Notes for the project.
hidden : boolean, optional: The hidden status of the item.

Returns:

id : integer

The ID for this project.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

name : string

The name of this project.

description : string

A description of the project.

users : list::

Users who can see the project. - id : integer

The ID of this user.

name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

tables : list::

schema : string
name : string
row_count : integer
column_count : integer
created_at : string/time
updated_at : string/time

surveys : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time

scripts : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

imports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

exports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

models : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

notebooks : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

services : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

workflows : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string
last_execution : dict::
- state : string
- updated_at : string/time

reports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

script_templates : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string

files : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
file_name : string
file_size : integer
expired : boolean

enhancements : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
last_run : dict::
- state : string
- updated_at : string/time

projects : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
description : string

all_objects : list::

project_id : integer
object_id : integer
object_type : string
fco_type : string
sub_type : string
name : string
icon : string
author : string
updated_at : string/time
archived : string

The archival status of the requested item(s).
hidden : boolean

The hidden status of the item.

note : string

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

parent_project : dict::

id : integer

The parent project’s ID.
name : integer

The parent project’s name.

put(self, project_id, *, name='DEFAULT', description='DEFAULT', note='DEFAULT', auto_share='DEFAULT')¶

Update a project

Parameters:

project_id : integer
name : string, optional: The name of this project.
description : string, optional: A description of the project.
note : string, optional: Notes for the project.
auto_share : boolean, optional: A toggle for sharing the objects within the project when the project is shared.This does not automatically share new objects to the project.

Returns:

id : integer

The ID for this project.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

name : string

The name of this project.

description : string

A description of the project.

users : list::

Users who can see the project. - id : integer

The ID of this user.

name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

tables : list::

schema : string
name : string
row_count : integer
column_count : integer
created_at : string/time
updated_at : string/time

surveys : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time

scripts : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

imports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

exports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

models : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

notebooks : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

services : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

workflows : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string
last_execution : dict::
- state : string
- updated_at : string/time

reports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

script_templates : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string

files : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
file_name : string
file_size : integer
expired : boolean

enhancements : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
last_run : dict::
- state : string
- updated_at : string/time

projects : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
description : string

all_objects : list::

project_id : integer
object_id : integer
object_type : string
fco_type : string
sub_type : string
name : string
icon : string
author : string
updated_at : string/time
archived : string

The archival status of the requested item(s).
hidden : boolean

The hidden status of the item.

note : string

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

parent_project : dict::

id : integer

The parent project’s ID.
name : integer

The parent project’s name.

put_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID for this project.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

name : string

The name of this project.

description : string

A description of the project.

users : list::

Users who can see the project. - id : integer

The ID of this user.

name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

auto_share : boolean

created_at : string/time

updated_at : string/time

tables : list::

schema : string
name : string
row_count : integer
column_count : integer
created_at : string/time
updated_at : string/time

surveys : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time

scripts : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

imports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

exports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
type : string
finished_at : string/time
state : string
last_run : dict::
- state : string
- updated_at : string/time

models : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

notebooks : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

services : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
current_deployment_id : integer
last_deploy : dict::
- state : string
- updated_at : string/time

workflows : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string
last_execution : dict::
- state : string
- updated_at : string/time

reports : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
state : string

script_templates : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string

files : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
file_name : string
file_size : integer
expired : boolean

enhancements : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
last_run : dict::
- state : string
- updated_at : string/time

projects : list::

id : integer

The item’s ID.
created_at : string/time
updated_at : string/time
name : string
description : string

all_objects : list::

project_id : integer
object_id : integer
object_type : string
fco_type : string
sub_type : string
name : string
icon : string
author : string
updated_at : string/time
archived : string

The archival status of the requested item(s).
hidden : boolean

The hidden status of the item.

note : string

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

parent_project : dict::

id : integer

The parent project’s ID.
name : integer

The parent project’s name.

put_parent_projects(self, id, parent_project_id)¶

Add an item to a Parent Project

Parameters:	id : integer The ID of the item. parent_project_id : integer The ID of the Parent Project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Queries¶

class Queries(session_kwargs, client, return_type='civis')¶

Methods

`delete_runs`(self, id, run_id)	Cancel a run
`get`(self, id)	Get details about a query
`get_runs`(self, id, run_id)	Check status of a run
`list`(self, \*[, database_id, author_id, …])	List
`list_runs`(self, id, \*[, limit, page_num, …])	List runs for the given query
`list_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`post`(self, database, sql, preview_rows, \*)	Execute a query
`post_runs`(self, id)	Start a run
`put_scripts`(self, id, script_id)	Update the query’s associated script

delete_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the query. run_id : integer The ID of the run.
Returns:	None Response code 202: success

get(self, id)¶

Get details about a query

Parameters:

id : integer: The query ID.

Returns:

id : integer

The query ID.

database : integer

The database ID.

sql : string

The SQL to execute.

credential : integer

The credential ID.

result_rows : list

A preview of rows returned by the query.

result_columns : list

A preview of columns returned by the query.

script_id : integer

The ID of the script associated with this query.

exception : string

Deprecated and not used.

error : string

The error message for this run, if present.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

hidden : boolean

The hidden status of the item.

name : string

The name of the query.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

started_at : string/date-time

The start time of the last run.

report_id : integer

The ID of the report associated with this query.

get_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the query.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
query_id : integer: The ID of the query.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list(self, *, database_id='DEFAULT', author_id='DEFAULT', created_before='DEFAULT', exclude_results='DEFAULT', hidden='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List

Parameters:

database_id : integer, optional: The database ID.
author_id : integer, optional: The author of the query.
created_before : string, optional: An upper bound for the creation date of the query.
exclude_results : boolean, optional: If true, does not return cached query results.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to created_at. Must be one of: created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer: The query ID.
database : integer: The database ID.
sql : string: The SQL to execute.
credential : integer: The credential ID.
result_rows : list: A preview of rows returned by the query.
result_columns : list: A preview of columns returned by the query.
script_id : integer: The ID of the script associated with this query.
exception : string: Deprecated and not used.
error : string: The error message for this run, if present.
created_at : string/time
updated_at : string/time
finished_at : string/date-time: The end time of the last run.
state : string: The state of the last run.
last_run_id : integer: The ID of the last run.
preview_rows : integer: The number of rows to save from the query’s result (maximum: 100).
started_at : string/date-time: The start time of the last run.
report_id : integer: The ID of the report associated with this query.

list_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given query

Parameters:

id : integer: The ID of the query.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer: The ID of the run.
query_id : integer: The ID of the query.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the query. 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.

post(self, database, sql, preview_rows, *, credential='DEFAULT', hidden='DEFAULT', interactive='DEFAULT', include_header='DEFAULT', compression='DEFAULT', column_delimiter='DEFAULT', unquoted='DEFAULT', filename_prefix='DEFAULT')¶

Execute a query

Parameters:

database : integer: The database ID.
sql : string: The SQL to execute.
preview_rows : integer: The number of rows to save from the query’s result (maximum: 100).
credential : integer, optional: The credential ID.
hidden : boolean, optional: The hidden status of the item.
interactive : boolean, optional: Deprecated and not used.
include_header : boolean, optional: Whether the CSV output should include a header row [default: true].
compression : string, optional: The type of compression. One of gzip or zip, or none [default: gzip].
column_delimiter : string, optional: The delimiter to use. One of comma or tab, or pipe [default: comma].
unquoted : boolean, optional: If true, will not quote fields.
filename_prefix : string, optional: The output filename prefix.

Returns:

id : integer: The query ID.
database : integer: The database ID.
sql : string: The SQL to execute.
credential : integer: The credential ID.
result_rows : list: A preview of rows returned by the query.
result_columns : list: A preview of columns returned by the query.
script_id : integer: The ID of the script associated with this query.
exception : string: Deprecated and not used.
error : string: The error message for this run, if present.
created_at : string/time
updated_at : string/time
finished_at : string/date-time: The end time of the last run.
state : string: The state of the last run.
last_run_id : integer: The ID of the last run.
hidden : boolean: The hidden status of the item.
interactive : boolean: Deprecated and not used.
preview_rows : integer: The number of rows to save from the query’s result (maximum: 100).
include_header : boolean: Whether the CSV output should include a header row [default: true].
compression : string: The type of compression. One of gzip or zip, or none [default: gzip].
column_delimiter : string: The delimiter to use. One of comma or tab, or pipe [default: comma].
unquoted : boolean: If true, will not quote fields.
filename_prefix : string: The output filename prefix.
started_at : string/date-time: The start time of the last run.
report_id : integer: The ID of the report associated with this query.

post_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the query.

Returns:

id : integer: The ID of the run.
query_id : integer: The ID of the query.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

put_scripts(self, id, script_id)¶

Update the query’s associated script

Parameters:

id : integer: The query ID.
script_id : integer: The ID of the script associated with this query.

Returns:

id : integer

The query ID.

database : integer

The database ID.

sql : string

The SQL to execute.

credential : integer

The credential ID.

result_rows : list

A preview of rows returned by the query.

result_columns : list

A preview of columns returned by the query.

script_id : integer

The ID of the script associated with this query.

exception : string

Deprecated and not used.

error : string

The error message for this run, if present.

created_at : string/time

updated_at : string/time

finished_at : string/date-time

The end time of the last run.

state : string

The state of the last run.

last_run_id : integer

The ID of the last run.

hidden : boolean

The hidden status of the item.

name : string

The name of the query.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

started_at : string/date-time

The start time of the last run.

report_id : integer

The ID of the report associated with this query.

Remote_Hosts¶

civis.resources._resources.Remote_Hosts¶: alias of civis.resources._resources.RemoteHosts

Reports¶

class Reports(session_kwargs, client, return_type='civis')¶

Methods

`delete_grants`(self, id)	Revoke permission for this report to perform Civis platform API operations on your behalf
`delete_projects`(self, id, project_id)	Remove a Report from a project
`delete_services_projects`(self, id, project_id)	Remove a Service Report from a project
`delete_services_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_services_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Show a single report
`get_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`get_services`(self, id)	Show a single service report
`list`(self, \*[, type, author, template_id, …])	List Reports
`list_git`(self, id)	Get the git metadata attached to an item
`list_git_commits`(self, id)	Get the git commits for an item
`list_projects`(self, id, \*[, hidden])	List the projects a Report belongs to
`list_services_projects`(self, id, \*[, hidden])	List the projects a Service Report belongs to
`list_services_shares`(self, id)	List users and groups permissioned on this object
`list_shares`(self, id)	List users and groups permissioned on this object
`patch`(self, id, \*[, name, script_id, …])	Update a report
`patch_git`(self, id, \*[, git_ref, …])	Update an attached git file
`patch_services`(self, id, \*[, name, …])	Update some attributes of this service report
`post`(self, \*[, script_id, name, code_body, …])	Create a report
`post_git_commits`(self, id, content, message, …)	Commit and push a new version of the file
`post_grants`(self, id)	Grant this report the ability to perform Civis platform API operations on your behalf
`post_refresh`(self, id)	Refresh the data in this Tableau report
`post_services`(self, service_id, \*[, …])	Create a service report
`put_archive`(self, id, status)	Update the archive status of this object
`put_git`(self, id, \*[, git_ref, git_branch, …])	Attach an item to a file in a git repo
`put_projects`(self, id, project_id)	Add a Report to a project
`put_services_projects`(self, id, project_id)	Add a Service Report to a project
`put_services_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_services_shares_users`(self, id, …[, …])	Set the permissions users have on this object
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_grants(self, id)¶

Revoke permission for this report to perform Civis platform API operations on your behalf

Parameters:	id : integer The ID of this report.
Returns:	None Response code 204: success

delete_projects(self, id, project_id)¶

Remove a Report from a project

Parameters:	id : integer The ID of the Report. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_services_projects(self, id, project_id)¶

Remove a Service Report from a project

Parameters:	id : integer The ID of the Service Report. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_services_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_services_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Show a single report

Parameters:

id : integer: The ID of this report.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

auth_data_url : string

auth_code_url : string

config : string

Any configuration metadata for this report.

valid_output_file : boolean

Whether the job (a script or a query) that backs the report currently has a valid output file.

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

app_state : dict

Any application state blob for this report.

use_viewers_tableau_username : boolean

Apply user level filtering on Tableau reports.

get_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

get_services(self, id)¶

Show a single service report

Parameters:

id : integer: The ID of this report.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

host : string

The host for the service report

display_url : string

The URL to display the service report.

service_id : integer

The id of the backing service

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

list(self, *, type='DEFAULT', author='DEFAULT', template_id='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Reports

Parameters:

type : string, optional: If specified, return report of these types. It accepts a comma-separated list, possible values are ‘tableau’ or ‘other’.
author : string, optional: If specified, return reports from this author. It accepts a comma-separated list of author ids.
template_id : integer, optional: If specified, return reports using the provided Template.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(s).
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

list_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Report belongs to

Parameters:

id : integer: The ID of the Report.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_services_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Service Report belongs to

Parameters:

id : integer: The ID of the Service Report.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_services_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, id, *, name='DEFAULT', script_id='DEFAULT', code_body='DEFAULT', config='DEFAULT', app_state='DEFAULT', provide_api_key='DEFAULT', template_id='DEFAULT', use_viewers_tableau_username='DEFAULT')¶

Update a report

Parameters:

id : integer: The ID of the report to modify.
name : string, optional: The name of the report.
script_id : integer, optional: The ID of the job (a script or a query) used to create this report.
code_body : string, optional: The code for the report visualization.
config : string, optional
app_state : dict, optional: The application state blob for this report.
provide_api_key : boolean, optional: Allow the report to provide an API key to front-end code.
template_id : integer, optional: The ID of the template used for this report. If null is passed, no template will back this report. Changes to the backing template will reset the report appState.
use_viewers_tableau_username : boolean, optional: Apply user level filtering on Tableau reports.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

auth_data_url : string

auth_code_url : string

config : string

Any configuration metadata for this report.

valid_output_file : boolean

Whether the job (a script or a query) that backs the report currently has a valid output file.

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

app_state : dict

Any application state blob for this report.

use_viewers_tableau_username : boolean

Apply user level filtering on Tableau reports.

patch_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

patch_services(self, id, *, name='DEFAULT', provide_api_key='DEFAULT')¶

Update some attributes of this service report

Parameters:

id : integer: The ID of this report.
name : string, optional: The name of the service report.
provide_api_key : boolean, optional: Whether the report requests an API Key from the report viewer.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

host : string

The host for the service report

display_url : string

The URL to display the service report.

service_id : integer

The id of the backing service

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

post(self, *, script_id='DEFAULT', name='DEFAULT', code_body='DEFAULT', app_state='DEFAULT', provide_api_key='DEFAULT', template_id='DEFAULT', hidden='DEFAULT')¶

Create a report

Parameters:

script_id : integer, optional: The ID of the job (a script or a query) used to create this report.
name : string, optional: The name of the report.
code_body : string, optional: The code for the report visualization.
app_state : dict, optional: Any application state blob for this report.
provide_api_key : boolean, optional: Allow the report to provide an API key to front-end code.
template_id : integer, optional: The ID of the template used for this report.
hidden : boolean, optional: The hidden status of the item.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

auth_data_url : string

auth_code_url : string

config : string

Any configuration metadata for this report.

valid_output_file : boolean

Whether the job (a script or a query) that backs the report currently has a valid output file.

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

app_state : dict

Any application state blob for this report.

use_viewers_tableau_username : boolean

Apply user level filtering on Tableau reports.

post_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

post_grants(self, id)¶

Grant this report the ability to perform Civis platform API operations on your behalf

Parameters:

id : integer: The ID of this report.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

auth_data_url : string

auth_code_url : string

config : string

Any configuration metadata for this report.

valid_output_file : boolean

Whether the job (a script or a query) that backs the report currently has a valid output file.

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

app_state : dict

Any application state blob for this report.

use_viewers_tableau_username : boolean

Apply user level filtering on Tableau reports.

post_refresh(self, id)¶

Refresh the data in this Tableau report

Parameters:	id : integer The ID of this report.
Returns:	id : integer The ID of this report. organization : dict:: id : integer The ID of this organization. tableau_refresh_usage : integer The number of tableau refreshes used this month. tableau_refresh_limit : integer The number of monthly tableau refreshes permitted to this organization. tableau_refresh_history : list The number of tableau refreshes used this month.

post_services(self, service_id, *, provide_api_key='DEFAULT')¶

Create a service report

Parameters:

service_id : integer: The id of the backing service
provide_api_key : boolean, optional: Whether the report requests an API Key from the report viewer.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

host : string

The host for the service report

display_url : string

The URL to display the service report.

service_id : integer

The id of the backing service

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

put_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID of this report.

name : string

The name of the report.

user : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

created_at : string/time

updated_at : string/time

projects : list::

A list of projects containing the report. - id : integer

The ID for the project.

name : string

The name of the project.

state : string

The status of the report’s last run.

finished_at : string/time

The time that the report’s last run finished.

viz_updated_at : string/time

The time that the report’s visualization was last updated.

script : dict::

id : integer

The ID for the script.
name : string

The name of the script.
sql : string

The raw SQL query for the script.

job_path : string

The link to details of the job that backs this report.

tableau_id : integer

type : string

template_id : integer

The ID of the template used for this report.

auth_thumbnail_url : string

URL for a thumbnail of the report.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

auth_data_url : string

auth_code_url : string

config : string

Any configuration metadata for this report.

valid_output_file : boolean

Whether the job (a script or a query) that backs the report currently has a valid output file.

provide_api_key : boolean

Whether the report requests an API Key from the report viewer.

api_key : string

A Civis API key that can be used by this report.

api_key_id : integer

The ID of the API key. Can be used for auditing API use by this report.

app_state : dict

Any application state blob for this report.

use_viewers_tableau_username : boolean

Apply user level filtering on Tableau reports.

put_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_projects(self, id, project_id)¶

Add a Report to a project

Parameters:	id : integer The ID of the Report. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_services_projects(self, id, project_id)¶

Add a Service Report to a project

Parameters:	id : integer The ID of the Service Report. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_services_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_services_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Scripts¶

class Scripts(session_kwargs, client, return_type='civis')¶

Methods

`delete_containers_projects`(self, id, project_id)	Remove a Container Script from a project
`delete_containers_runs`(self, id, run_id)	Cancel a run
`delete_containers_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_containers_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_custom_projects`(self, id, project_id)	Remove a Custom Script from a project
`delete_custom_runs`(self, id, run_id)	Cancel a run
`delete_custom_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_custom_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_javascript_projects`(self, id, project_id)	Remove a JavaScript Script from a project
`delete_javascript_runs`(self, id, run_id)	Cancel a run
`delete_javascript_shares_groups`(self, id, …)	Revoke the permissions a group has on this object
`delete_javascript_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_python3_projects`(self, id, project_id)	Remove a Python Script from a project
`delete_python3_runs`(self, id, run_id)	Cancel a run
`delete_python3_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_python3_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_r_projects`(self, id, project_id)	Remove an R Script from a project
`delete_r_runs`(self, id, run_id)	Cancel a run
`delete_r_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_r_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_sql_projects`(self, id, project_id)	Remove a SQL script from a project
`delete_sql_runs`(self, id, run_id)	Cancel a run
`delete_sql_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_sql_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get details about a script
`get_containers`(self, id)	View a container
`get_containers_runs`(self, id, run_id)	Check status of a run
`get_custom`(self, id)	Get a Custom Script
`get_custom_runs`(self, id, run_id)	Check status of a run
`get_javascript`(self, id)	Get a JavaScript Script
`get_javascript_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`get_javascript_runs`(self, id, run_id)	Check status of a run
`get_python3`(self, id)	Get a Python Script
`get_python3_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`get_python3_runs`(self, id, run_id)	Check status of a run
`get_r`(self, id)	Get an R Script
`get_r_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`get_r_runs`(self, id, run_id)	Check status of a run
`get_sql`(self, id)	Get a SQL script
`get_sql_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`get_sql_runs`(self, id, run_id)	Check status of a run
`list`(self, \*[, type, category, author, …])	List Scripts
`list_containers_projects`(self, id, \*[, hidden])	List the projects a Container Script belongs to
`list_containers_runs`(self, id, \*[, limit, …])	List runs for the given container
`list_containers_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_containers_runs_outputs`(self, id, …)	List the outputs for a run
`list_containers_shares`(self, id)	List users and groups permissioned on this object
`list_custom`(self, \*[, from_template_id, …])	List Custom Scripts
`list_custom_projects`(self, id, \*[, hidden])	List the projects a Custom Script belongs to
`list_custom_runs`(self, id, \*[, limit, …])	List runs for the given custom
`list_custom_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_custom_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`list_custom_shares`(self, id)	List users and groups permissioned on this object
`list_history`(self, id)	Get the run history and outputs of this script
`list_javascript_git`(self, id)	Get the git metadata attached to an item
`list_javascript_git_commits`(self, id)	Get the git commits for an item
`list_javascript_projects`(self, id, \*[, hidden])	List the projects a JavaScript Script belongs to
`list_javascript_runs`(self, id, \*[, limit, …])	List runs for the given javascript
`list_javascript_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_javascript_runs_outputs`(self, id, …)	List the outputs for a run
`list_javascript_shares`(self, id)	List users and groups permissioned on this object
`list_python3_git`(self, id)	Get the git metadata attached to an item
`list_python3_git_commits`(self, id)	Get the git commits for an item
`list_python3_projects`(self, id, \*[, hidden])	List the projects a Python Script belongs to
`list_python3_runs`(self, id, \*[, limit, …])	List runs for the given python
`list_python3_runs_logs`(self, id, run_id, \*)	Get the logs for a run
`list_python3_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`list_python3_shares`(self, id)	List users and groups permissioned on this object
`list_r_git`(self, id)	Get the git metadata attached to an item
`list_r_git_commits`(self, id)	Get the git commits for an item
`list_r_projects`(self, id, \*[, hidden])	List the projects an R Script belongs to
`list_r_runs`(self, id, \*[, limit, page_num, …])	List runs for the given r
`list_r_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`list_r_runs_outputs`(self, id, run_id, \*[, …])	List the outputs for a run
`list_r_shares`(self, id)	List users and groups permissioned on this object
`list_sql_git`(self, id)	Get the git metadata attached to an item
`list_sql_git_commits`(self, id)	Get the git commits for an item
`list_sql_projects`(self, id, \*[, hidden])	List the projects a SQL script belongs to
`list_sql_runs`(self, id, \*[, limit, …])	List runs for the given sql
`list_sql_runs_logs`(self, id, run_id, \*[, …])	Get the logs for a run
`list_sql_runs_outputs`(self, id, run_id, \*)	List the outputs for a run
`list_sql_shares`(self, id)	List users and groups permissioned on this object
`list_types`(self)	List available script types
`patch`(self, id, \*[, name, sql, params, …])	Update a script
`patch_containers`(self, id, \*[, name, …])	Update a container
`patch_custom`(self, id, \*[, name, …])	Update some attributes of this Custom Script
`patch_javascript`(self, id, \*[, name, …])	Update some attributes of this JavaScript Script
`patch_javascript_git`(self, id, \*[, …])	Update an attached git file
`patch_python3`(self, id, \*[, name, …])	Update some attributes of this Python Script
`patch_python3_git`(self, id, \*[, git_ref, …])	Update an attached git file
`patch_r`(self, id, \*[, name, parent_id, …])	Update some attributes of this R Script
`patch_r_git`(self, id, \*[, git_ref, …])	Update an attached git file
`patch_sql`(self, id, \*[, name, parent_id, …])	Update some attributes of this SQL script
`patch_sql_git`(self, id, \*[, git_ref, …])	Update an attached git file
`post`(self, name, remote_host_id, …[, …])	Create a script
`post_cancel`(self, id)	Cancel a run
`post_containers`(self, required_resources, …)	Create a container
`post_containers_clone`(self, id, \*[, …])	Clone this Container Script
`post_containers_runs`(self, id)	Start a run
`post_containers_runs_logs`(self, id, run_id, \*)	Add log messages
`post_containers_runs_outputs`(self, id, …)	Add an output for a run
`post_custom`(self, from_template_id, \*[, …])	Create a Custom Script
`post_custom_clone`(self, id, \*[, …])	Clone this Custom Script
`post_custom_runs`(self, id)	Start a run
`post_custom_runs_outputs`(self, id, run_id, …)	Add an output for a run
`post_javascript`(self, name, source, …[, …])	Create a JavaScript Script
`post_javascript_clone`(self, id, \*[, …])	Clone this JavaScript Script
`post_javascript_git_commits`(self, id, …)	Commit and push a new version of the file
`post_javascript_runs`(self, id)	Start a run
`post_javascript_runs_outputs`(self, id, …)	Add an output for a run
`post_python3`(self, name, source, \*[, …])	Create a Python Script
`post_python3_clone`(self, id, \*[, …])	Clone this Python Script
`post_python3_git_commits`(self, id, content, …)	Commit and push a new version of the file
`post_python3_runs`(self, id)	Start a run
`post_python3_runs_outputs`(self, id, run_id, …)	Add an output for a run
`post_r`(self, name, source, \*[, parent_id, …])	Create an R Script
`post_r_clone`(self, id, \*[, clone_schedule, …])	Clone this R Script
`post_r_git_commits`(self, id, content, …)	Commit and push a new version of the file
`post_r_runs`(self, id)	Start a run
`post_r_runs_outputs`(self, id, run_id, …)	Add an output for a run
`post_run`(self, id)	Run a script
`post_sql`(self, name, sql, remote_host_id, …)	Create a SQL script
`post_sql_clone`(self, id, \*[, …])	Clone this SQL script
`post_sql_git_commits`(self, id, content, …)	Commit and push a new version of the file
`post_sql_runs`(self, id)	Start a run
`put_containers`(self, id, required_resources, …)	Edit a container
`put_containers_archive`(self, id, status)	Update the archive status of this object
`put_containers_projects`(self, id, project_id)	Add a Container Script to a project
`put_containers_shares_groups`(self, id, …)	Set the permissions groups has on this object
`put_containers_shares_users`(self, id, …[, …])	Set the permissions users have on this object
`put_custom`(self, id, \*[, name, parent_id, …])	Replace all attributes of this Custom Script
`put_custom_archive`(self, id, status)	Update the archive status of this object
`put_custom_projects`(self, id, project_id)	Add a Custom Script to a project
`put_custom_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_custom_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object
`put_javascript`(self, id, name, source, …)	Replace all attributes of this JavaScript Script
`put_javascript_archive`(self, id, status)	Update the archive status of this object
`put_javascript_git`(self, id, \*[, git_ref, …])	Attach an item to a file in a git repo
`put_javascript_projects`(self, id, project_id)	Add a JavaScript Script to a project
`put_javascript_shares_groups`(self, id, …)	Set the permissions groups has on this object
`put_javascript_shares_users`(self, id, …[, …])	Set the permissions users have on this object
`put_python3`(self, id, name, source, \*[, …])	Replace all attributes of this Python Script
`put_python3_archive`(self, id, status)	Update the archive status of this object
`put_python3_git`(self, id, \*[, git_ref, …])	Attach an item to a file in a git repo
`put_python3_projects`(self, id, project_id)	Add a Python Script to a project
`put_python3_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_python3_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object
`put_r`(self, id, name, source, \*[, …])	Replace all attributes of this R Script
`put_r_archive`(self, id, status)	Update the archive status of this object
`put_r_git`(self, id, \*[, git_ref, …])	Attach an item to a file in a git repo
`put_r_projects`(self, id, project_id)	Add an R Script to a project
`put_r_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_r_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object
`put_sql`(self, id, name, sql, remote_host_id, …)	Replace all attributes of this SQL script
`put_sql_archive`(self, id, status)	Update the archive status of this object
`put_sql_git`(self, id, \*[, git_ref, …])	Attach an item to a file in a git repo
`put_sql_projects`(self, id, project_id)	Add a SQL script to a project
`put_sql_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_sql_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object

delete_containers_projects(self, id, project_id)¶

Remove a Container Script from a project

Parameters:	id : integer The ID of the Container Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_containers_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the container. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_containers_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_containers_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_custom_projects(self, id, project_id)¶

Remove a Custom Script from a project

Parameters:	id : integer The ID of the Custom Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_custom_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the custom. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_custom_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_custom_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_javascript_projects(self, id, project_id)¶

Remove a JavaScript Script from a project

Parameters:	id : integer The ID of the JavaScript Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_javascript_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the javascript. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_javascript_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_javascript_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_python3_projects(self, id, project_id)¶

Remove a Python Script from a project

Parameters:	id : integer The ID of the Python Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_python3_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the python. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_python3_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_python3_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_r_projects(self, id, project_id)¶

Remove an R Script from a project

Parameters:	id : integer The ID of the R Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_r_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the r. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_r_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_r_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_sql_projects(self, id, project_id)¶

Remove a SQL script from a project

Parameters:	id : integer The ID of the SQL script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_sql_runs(self, id, run_id)¶

Cancel a run

Parameters:	id : integer The ID of the sql. run_id : integer The ID of the run.
Returns:	None Response code 202: success

delete_sql_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_sql_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Get details about a script

Parameters:

id : integer: The ID for the script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of script.

created_at : string/time

The time this script was created.

updated_at : string/time

The time this script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

template_script_id : integer

The ID of the template script, if any.

get_containers(self, id)¶

View a container

Parameters:

id : integer: The ID for the script.

Returns:

id : integer

The ID for the script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

get_containers_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the container.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
container_id : integer: The ID of the container.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

get_custom(self, id)¶

Get a Custom Script

Parameters:

id : integer

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

get_custom_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the custom.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
custom_id : integer: The ID of the custom.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

get_javascript(self, id)¶

Get a JavaScript Script

Parameters:

id : integer

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

get_javascript_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

get_javascript_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the javascript.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
javascript_id : integer: The ID of the javascript.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

get_python3(self, id)¶

Get a Python Script

Parameters:

id : integer

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

get_python3_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

get_python3_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the python.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
python_id : integer: The ID of the python.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

get_r(self, id)¶

Get an R Script

Parameters:

id : integer

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

get_r_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

get_r_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the r.
run_id : integer: The ID of the run.

Returns:

id : integer: The ID of the run.
r_id : integer: The ID of the r.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

get_sql(self, id)¶

Get a SQL script

Parameters:

id : integer

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

get_sql_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

get_sql_runs(self, id, run_id)¶

Check status of a run

Parameters:

id : integer: The ID of the sql.
run_id : integer: The ID of the run.

Returns:

id : integer

The ID of this run.

sql_id : integer

The ID of this sql.

state : string

The state of this run.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started.

finished_at : string/time

The time that this run finished.

error : string

The error message for this run, if present.

output : list::

A list of the outputs of this script. - output_name : string

The name of the output file.

file_id : integer

The unique ID of the output file.
path : string

The temporary link to download this output file, valid for 36 hours.

output_cached_on : string/time

The time that the output was originally exported, if a cache entry was used by the run.

list(self, *, type='DEFAULT', category='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Scripts

Parameters:

type : string, optional: If specified, return items of these types. The valid types are sql, python3, javascript, r, and containers.
category : string, optional: A job category for filtering scripts. Must be one of script, import, export, and enhancement.
author : string, optional: If specified, return items from this author. Must use user IDs. A comma separated list of IDs is also accepted to return items from multiple authors.
status : string, optional: If specified, returns items 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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(s).
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

is_template : boolean

Whether others scripts use this one as a template.

from_template_id : integer

The ID of the template this script uses, if any.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

template_script_id : integer

The ID of the template script, if any.

list_containers_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Container Script belongs to

Parameters:

id : integer: The ID of the Container Script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_containers_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given container

Parameters:

id : integer: The ID of the container.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer: The ID of the run.
container_id : integer: The ID of the container.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_containers_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the container. run_id : integer The ID of the run. last_id : integer, optional The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt. limit : integer, optional The maximum number of log messages to return. Default of 10000.
Returns:	id : integer The ID of the log. created_at : string/date-time The time the log was created. message : string The log message. level : string The level of the log. One of unknown,fatal,error,warn,info,debug.

list_containers_runs_outputs(self, 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 container script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_containers_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

Returns:

readers : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

writers : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

owners : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_custom(self, *, from_template_id='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Custom Scripts

Parameters:

from_template_id : string, optional: If specified, return scripts based on the template with this ID. Specify multiple IDs as a comma-separated list.
author : string, optional: If specified, return items from this author. Must use user IDs. A comma separated list of IDs is also accepted to return items from multiple authors.
status : string, optional: If specified, returns items 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 items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(s).
limit : integer, optional: Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

from_template_id : integer

The ID of the template script.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

archived : string

The archival status of the requested item(s).

last_successful_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

list_custom_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Custom Script belongs to

Parameters:

id : integer: The ID of the Custom Script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_custom_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given custom

Parameters:

id : integer: The ID of the custom.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer: The ID of the run.
custom_id : integer: The ID of the custom.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_custom_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the custom. run_id : integer The ID of the run. last_id : integer, optional The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt. limit : integer, optional The maximum number of log messages to return. Default of 10000.
Returns:	id : integer The ID of the log. created_at : string/date-time The time the log was created. message : string The log message. level : string The level of the log. One of unknown,fatal,error,warn,info,debug.

list_custom_runs_outputs(self, 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 custom script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_custom_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

Returns:

readers : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

writers : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

owners : dict::

users : list::
- id : integer
- name : string
groups : list::
- id : integer
- name : string

total_user_shares : integer

For owners, the number of total users shared. For writers and readers, the number of visible users shared.

total_group_shares : integer

For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_history(self, id)¶

Get the run history and outputs of this script

Parameters:

id : integer: The ID for the script.

Returns:

id : integer

The ID of this run.

sql_id : integer

The ID of this sql.

state : string

The state of this run.

is_cancel_requested : boolean

True if run cancel requested, else false.

finished_at : string/time

The time that this run finished.

error : string

The error message for this run, if present.

output : list::

A list of the outputs of this script. - output_name : string

The name of the output file.

file_id : integer

The unique ID of the output file.
path : string

The temporary link to download this output file, valid for 36 hours.

list_javascript_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_javascript_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_javascript_projects(self, id, *, hidden='DEFAULT')¶

List the projects a JavaScript Script belongs to

Parameters:

id : integer: The ID of the JavaScript Script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_javascript_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given javascript

Parameters:

id : integer: The ID of the javascript.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

id : integer: The ID of the run.
javascript_id : integer: The ID of the javascript.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_javascript_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the javascript. run_id : integer The ID of the run. last_id : integer, optional The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt. limit : integer, optional The maximum number of log messages to return. Default of 10000.
Returns:	id : integer The ID of the log. created_at : string/date-time The time the log was created. message : string The log message. level : string The level of the log. One of unknown,fatal,error,warn,info,debug.

list_javascript_runs_outputs(self, 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 javascript script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_javascript_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_python3_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_python3_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_python3_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Python Script belongs to

Parameters:

id : integer: The ID of the Python Script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_python3_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given python

Parameters:

id : integer: The ID of the python.
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.
python_id : integer: The ID of the python.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_python3_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the python. 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_python3_runs_outputs(self, 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 python script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_python3_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_r_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_r_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_r_projects(self, id, *, hidden='DEFAULT')¶

List the projects an R Script belongs to

Parameters:

id : integer: The ID of the R Script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_r_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given r

Parameters:

id : integer: The ID of the r.
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.
r_id : integer: The ID of the r.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

list_r_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the r. 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_r_runs_outputs(self, 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 r script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_r_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_sql_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_sql_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_sql_projects(self, id, *, hidden='DEFAULT')¶

List the projects a SQL script belongs to

Parameters:

id : integer: The ID of the SQL script.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_sql_runs(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List runs for the given sql

Parameters:

id : integer: The ID of the sql.
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 this run.

sql_id : integer

The ID of this sql.

state : string

The state of this run.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started.

finished_at : string/time

The time that this run finished.

error : string

The error message for this run, if present.

output : list::

A list of the outputs of this script. - output_name : string

The name of the output file.

file_id : integer

The unique ID of the output file.
path : string

The temporary link to download this output file, valid for 36 hours.

output_cached_on : string/time

The time that the output was originally exported, if a cache entry was used by the run.

list_sql_runs_logs(self, id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶

Get the logs for a run

Parameters:	id : integer The ID of the sql. 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_sql_runs_outputs(self, 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 sql script.
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, Credential, or JSONValue
object_id : integer: The ID of the output.
name : string: The name of the output.
link : string: The hypermedia link to the output.
value : string

list_sql_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self)¶

List available script types

Returns:	name : string The name of the type.

patch(self, id, *, name='DEFAULT', sql='DEFAULT', params='DEFAULT', arguments='DEFAULT', template_script_id='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', parent_id='DEFAULT')¶

Update a script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

sql : string, optional

The raw SQL query for the script.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. Cannot be set if this script uses a template script. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

template_script_id : integer, optional

The ID of the template script, if any. A script cannot both have a template script and be a template for other scripts.

schedule : dict, optional::

scheduled : boolean

If the item 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

The ID of the parent job that will trigger this script

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of script.

created_at : string/time

The time this script was created.

updated_at : string/time

The time this script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

template_script_id : integer

The ID of the template script, if any.

patch_containers(self, id, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', required_resources='DEFAULT', repo_http_uri='DEFAULT', repo_ref='DEFAULT', remote_host_credential_id='DEFAULT', git_credential_id='DEFAULT', docker_command='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', time_zone='DEFAULT', partition_label='DEFAULT', target_project_id='DEFAULT')¶

Update a container

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the container.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string, optional

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string, optional

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer, optional

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer, optional

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string, optional

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

docker_image_name : string, optional

The name of the docker image to pull from DockerHub.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

time_zone : string, optional

The time zone of this script.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

target_project_id : integer, optional

Target project to which script outputs will be added.

Returns:

id : integer

The ID for the script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

patch_custom(self, id, *, name='DEFAULT', parent_id='DEFAULT', arguments='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', partition_label='DEFAULT')¶

Update some attributes of this Custom Script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

remote_host_id : integer, optional

The remote host ID that this script will connect to.

credential_id : integer, optional

The credential that this script will use.

schedule : dict, optional::

scheduled : boolean

If the item 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.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string, optional

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

patch_javascript(self, id, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', source='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT')¶

Update some attributes of this JavaScript Script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

source : string, optional

The body/text of the script.

remote_host_id : integer, optional

The remote host ID that this script will connect to.

credential_id : integer, optional

The credential that this script will use.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

patch_javascript_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

patch_python3(self, id, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', source='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Update some attributes of this Python Script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string, optional

The body/text of the script.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

patch_python3_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

patch_r(self, id, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', source='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Update some attributes of this R Script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string, optional

The body/text of the script.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

patch_r_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

patch_sql(self, id, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', sql='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT', csv_settings='DEFAULT')¶

Update some attributes of this SQL script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

sql : string, optional

The raw SQL query for the script.

remote_host_id : integer, optional

The remote host ID that this script will connect to.

credential_id : integer, optional

The credential that this script will use.

csv_settings : dict, optional::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

patch_sql_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

post(self, name, remote_host_id, credential_id, sql, *, params='DEFAULT', arguments='DEFAULT', template_script_id='DEFAULT', notifications='DEFAULT', hidden='DEFAULT')¶

Create a script

Parameters:

name : string

The name of the script.

remote_host_id : integer

The database ID.

credential_id : integer

The credential ID.

sql : string

The raw SQL query for the script.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. Cannot be set if this script uses a template script. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

template_script_id : integer, optional

The ID of the template script, if any. A script cannot both have a template script and be a template for other scripts.

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.

hidden : boolean, optional

The hidden status of the item.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

template_script_id : integer

The ID of the template script, if any.

post_cancel(self, 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_containers(self, required_resources, docker_image_name, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', repo_http_uri='DEFAULT', repo_ref='DEFAULT', remote_host_credential_id='DEFAULT', git_credential_id='DEFAULT', docker_command='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', time_zone='DEFAULT', partition_label='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT')¶

Create a container

Parameters:

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

docker_image_name : string

The name of the docker image to pull from DockerHub.

name : string, optional

The name of the container.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

repo_http_uri : string, optional

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string, optional

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer, optional

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer, optional

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string, optional

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

time_zone : string, optional

The time zone of this script.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

Returns:

id : integer

The ID for the script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

post_containers_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this Container Script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

post_containers_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the container.

Returns:

id : integer: The ID of the run.
container_id : integer: The ID of the container.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

post_containers_runs_logs(self, id, run_id, *, message='DEFAULT', level='DEFAULT', messages='DEFAULT', child_job_id='DEFAULT')¶

Add log messages

Parameters:

id : integer

The ID of the script.

run_id : integer

The ID of the script run.

message : string, optional

The log message to store.

level : string, optional

The log level of this message [default: info]

messages : list, optional::

If specified, a batch of logs to store. If createdAt timestamps for the logs are supplied, the ordering of this list is not preserved, and the timestamps are used to sort the logs.If createdAt timestamps are not supplied, the ordering of this list is preserved and the logs are given the timestamp of when they were received. - message : string

The log message to store.

level : string

The log level of this message [default: info]
created_at : string/date-time

The timestamp of this message in ISO 8601 format. This is what logs are ordered by, so it is recommended to use timestamps with nanosecond precision. If absent, defaults to the time that the log was received by the API.

child_job_id : integer, optional

The ID of the child job the message came from.

Returns:

None: Response code 204: success

post_containers_runs_outputs(self, id, run_id, object_type, object_id)¶

Add an output for a run

Parameters:	id : integer The ID of the container script. run_id : integer The ID of the run. object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output.
Returns:	object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output. name : string The name of the output. link : string The hypermedia link to the output. value : string

post_custom(self, from_template_id, *, name='DEFAULT', parent_id='DEFAULT', arguments='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', partition_label='DEFAULT')¶

Create a Custom Script

Parameters:

from_template_id : integer

The ID of the template script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

remote_host_id : integer, optional

The remote host ID that this script will connect to.

credential_id : integer, optional

The credential that this script will use.

schedule : dict, optional::

scheduled : boolean

If the item 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.

time_zone : string, optional

The time zone of this script.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string, optional

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

post_custom_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this Custom Script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

post_custom_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the custom.

Returns:

id : integer: The ID of the run.
custom_id : integer: The ID of the custom.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

post_custom_runs_outputs(self, id, run_id, object_type, object_id)¶

Add an output for a run

Parameters:	id : integer The ID of the custom script. run_id : integer The ID of the run. object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output.
Returns:	object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output. name : string The name of the output. link : string The hypermedia link to the output. value : string

post_javascript(self, name, source, remote_host_id, credential_id, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT')¶

Create a JavaScript Script

Parameters:

name : string

The name of the script.

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

post_javascript_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this JavaScript Script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

post_javascript_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

post_javascript_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the javascript.

Returns:

id : integer: The ID of the run.
javascript_id : integer: The ID of the javascript.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

post_javascript_runs_outputs(self, id, run_id, object_type, object_id)¶

Add an output for a run

Parameters:	id : integer The ID of the javascript script. run_id : integer The ID of the run. object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output.
Returns:	object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output. name : string The name of the output. link : string The hypermedia link to the output. value : string

post_python3(self, name, source, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Create a Python Script

Parameters:

name : string

The name of the script.

source : string

The body/text of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

post_python3_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this Python Script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

post_python3_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

post_python3_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the python.

Returns:

id : integer: The ID of the run.
python_id : integer: The ID of the python.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

post_python3_runs_outputs(self, id, run_id, object_type, object_id)¶

Add an output for a run

Parameters:	id : integer The ID of the python script. run_id : integer The ID of the run. object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output.
Returns:	object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output. name : string The name of the output. link : string The hypermedia link to the output. value : string

post_r(self, name, source, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Create an R Script

Parameters:

name : string

The name of the script.

source : string

The body/text of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

post_r_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this R Script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

post_r_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

post_r_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the r.

Returns:

id : integer: The ID of the run.
r_id : integer: The ID of the r.
state : string: The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean: True if run cancel requested, else false.
started_at : string/time: The time the last run started at.
finished_at : string/time: The time the last run completed.
error : string: The error, if any, returned by the run.

post_r_runs_outputs(self, id, run_id, object_type, object_id)¶

Add an output for a run

Parameters:	id : integer The ID of the r script. run_id : integer The ID of the run. object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output.
Returns:	object_type : string The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue object_id : integer The ID of the output. name : string The name of the output. link : string The hypermedia link to the output. value : string

post_run(self, id)¶

Run a script

Parameters:	id : integer The ID for the script.
Returns:	None Response code 204: success

post_sql(self, name, sql, remote_host_id, credential_id, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT', target_project_id='DEFAULT', csv_settings='DEFAULT')¶

Create a SQL script

Parameters:

name : string

The name of the script.

sql : string

The raw SQL query for the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

hidden : boolean, optional

The hidden status of the item.

target_project_id : integer, optional

Target project to which script outputs will be added.

csv_settings : dict, optional::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

post_sql_clone(self, id, *, clone_schedule='DEFAULT', clone_triggers='DEFAULT', clone_notifications='DEFAULT')¶

Clone this SQL script

Parameters:

id : integer: The ID for the script.
clone_schedule : boolean, optional: If true, also copy the schedule to the new script.
clone_triggers : boolean, optional: If true, also copy the triggers to the new script.
clone_notifications : boolean, optional: If true, also copy the notifications to the new script.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

post_sql_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

post_sql_runs(self, id)¶

Start a run

Parameters:

id : integer: The ID of the sql.

Returns:

id : integer

The ID of this run.

sql_id : integer

The ID of this sql.

state : string

The state of this run.

is_cancel_requested : boolean

True if run cancel requested, else false.

started_at : string/time

The time the last run started.

finished_at : string/time

The time that this run finished.

error : string

The error message for this run, if present.

output : list::

A list of the outputs of this script. - output_name : string

The name of the output file.

file_id : integer

The unique ID of the output file.
path : string

The temporary link to download this output file, valid for 36 hours.

output_cached_on : string/time

The time that the output was originally exported, if a cache entry was used by the run.

put_containers(self, id, required_resources, docker_image_name, *, name='DEFAULT', parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', repo_http_uri='DEFAULT', repo_ref='DEFAULT', remote_host_credential_id='DEFAULT', git_credential_id='DEFAULT', docker_command='DEFAULT', docker_image_tag='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', time_zone='DEFAULT', partition_label='DEFAULT', target_project_id='DEFAULT')¶

Edit a container

Parameters:

id : integer

The ID for the script.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

docker_image_name : string

The name of the docker image to pull from DockerHub.

name : string, optional

The name of the container.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

repo_http_uri : string, optional

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string, optional

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer, optional

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer, optional

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string, optional

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

time_zone : string, optional

The time zone of this script.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

target_project_id : integer, optional

Target project to which script outputs will be added.

Returns:

id : integer

The ID for the script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

put_containers_archive(self, 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 script.

name : string

The name of the container.

type : string

The type of the script (e.g Container)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

template_dependents_count : integer

How many other scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

repo_http_uri : string

The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.

repo_ref : string

The tag or branch of the github repo to clone into the container.

remote_host_credential_id : integer

The id of the database credentials to pass into the environment of the container.

git_credential_id : integer

The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.

docker_command : string

The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]. Defaults to the Docker image’s ENTRYPOINT/CMD.

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.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

time_zone : string

The time zone of this script.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

put_containers_projects(self, id, project_id)¶

Add a Container Script to a project

Parameters:	id : integer The ID of the Container Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_containers_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_containers_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_custom(self, id, *, name='DEFAULT', parent_id='DEFAULT', arguments='DEFAULT', remote_host_id='DEFAULT', credential_id='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', partition_label='DEFAULT')¶

Replace all attributes of this Custom Script

Parameters:

id : integer

The ID for the script.

name : string, optional

The name of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

remote_host_id : integer, optional

The remote host ID that this script will connect to.

credential_id : integer, optional

The credential that this script will use.

schedule : dict, optional::

scheduled : boolean

If the item 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.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string, optional

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

put_custom_archive(self, 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 script.

name : string

The name of the script.

type : string

The type of the script (e.g Custom)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template script.

ui_report_url : integer

The url of the custom HTML.

ui_report_id : integer

The id of the report with the custom HTML.

ui_report_provide_api_key : boolean

Whether the ui report requests an API Key from the report viewer.

template_script_name : string

The name of the template script.

template_note : string

The template’s note.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

archived : string

The archival status of the requested item(s).

target_project_id : integer

Target project to which script outputs will be added.

last_successful_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.

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares.
memory : integer

The amount of RAM to allocate for the container (in MB).
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

partition_label : string

The partition label used to run this object. Only applicable for jobs using Docker.Not generally available. Beware this attribute may be removed in the future.

put_custom_projects(self, id, project_id)¶

Add a Custom Script to a project

Parameters:	id : integer The ID of the Custom Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_custom_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_custom_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_javascript(self, id, name, source, remote_host_id, credential_id, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT')¶

Replace all attributes of this JavaScript Script

Parameters:

id : integer

The ID for the script.

name : string

The name of the script.

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

put_javascript_archive(self, 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 script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

source : string

The body/text of the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

put_javascript_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_javascript_projects(self, id, project_id)¶

Add a JavaScript Script to a project

Parameters:	id : integer The ID of the JavaScript Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_javascript_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_javascript_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_python3(self, id, name, source, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Replace all attributes of this Python Script

Parameters:

id : integer

The ID for the script.

name : string

The name of the script.

source : string

The body/text of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

put_python3_archive(self, 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 script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

put_python3_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_python3_projects(self, id, project_id)¶

Add a Python Script to a project

Parameters:	id : integer The ID of the Python Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_python3_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_python3_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_r(self, id, name, source, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', required_resources='DEFAULT', instance_type='DEFAULT', cancel_timeout='DEFAULT', docker_image_tag='DEFAULT', partition_label='DEFAULT')¶

Replace all attributes of this R Script

Parameters:

id : integer

The ID for the script.

name : string

The name of the script.

source : string

The body/text of the script.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

required_resources : dict, optional::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string, optional

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

cancel_timeout : integer, optional

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub.

partition_label : string, optional

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

put_r_archive(self, 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 script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

required_resources : dict::

cpu : integer

The number of CPU shares to allocate for the container. Each core has 1000 shares. Must be at least 2 shares.
memory : integer

The amount of RAM to allocate for the container (in MB). Must be at least 4 MB.
disk_space : number/float

The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.

instance_type : string

The EC2 instance type to deploy to. Only available for jobs running on kubernetes.

source : string

The body/text of the script.

cancel_timeout : integer

The amount of time (in seconds) to wait before forcibly terminating the script. When the script is cancelled, it is first sent a TERM signal. If the script is still running after the timeout, it is sent a KILL signal. Defaults to 0.

docker_image_tag : string

The tag of the docker image to pull from DockerHub.

partition_label : string

The partition label used to run this object. Not generally available. Beware this attribute may be removed in the future.

put_r_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_r_projects(self, id, project_id)¶

Add an R Script to a project

Parameters:	id : integer The ID of the R Script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_r_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_r_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_sql(self, id, name, sql, remote_host_id, credential_id, *, parent_id='DEFAULT', user_context='DEFAULT', params='DEFAULT', arguments='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', target_project_id='DEFAULT', csv_settings='DEFAULT')¶

Replace all attributes of this SQL script

Parameters:

id : integer

The ID for the script.

name : string

The name of the script.

sql : string

The raw SQL query for the script.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

parent_id : integer, optional

The ID of the parent job that will trigger this script

user_context : string, optional

“runner” or “author”, who to execute the script as when run as a template.

params : list, optional::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict, optional

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

schedule : dict, optional::

scheduled : boolean

If the item 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.

next_run_at : string/time, optional

The time of the next scheduled run.

time_zone : string, optional

The time zone of this script.

target_project_id : integer, optional

Target project to which script outputs will be added.

csv_settings : dict, optional::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

Returns:

id : integer

The ID for the script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

put_sql_archive(self, 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 script.

name : string

The name of the script.

type : string

The type of the script (e.g SQL, Container, Python, R, JavaScript)

created_at : string/time

The time this script was created.

updated_at : string/time

The time the script was last updated.

author : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

state : string

The status of the script’s last run.

finished_at : string/time

The time that the script’s last run finished.

category : string

The category of the script.

projects : list::

A list of projects containing the script. - id : integer

The ID for the project.

name : string

The name of the project.

parent_id : integer

The ID of the parent job that will trigger this script

user_context : string

“runner” or “author”, who to execute the script as when run as a template.

params : list::

A definition of the parameters this script accepts in the arguments field. - name : string

The variable’s name as used within your code.

label : string

The label to present to users when asking them for the value.
description : string

A short sentence or fragment describing this parameter to the end user.
type : string

The type of parameter. Valid options: string, multi_line_string, integer, float, bool, file, table, database, credential_aws, credential_redshift, or credential_custom
required : boolean

Whether this param is required.
value : string

The value you would like to set this param to. Setting this value makes this parameter a fixed param.
default : string

If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool’s or false, False, f, n, no, or 0 for false bool’s. Cannot be used for parameters that are required or a credential type.
allowed_values : list

The possible values this parameter can take, effectively making this an enumerable parameter. Allowed values is an array of hashes of the following format: {label: ‘Import’, ‘value’: ‘import’}

arguments : dict

Parameter-value pairs to use when running this script. Only settable if this script has defined parameters.

is_template : boolean

Whether others scripts use this one as a template.

published_as_template_id : integer

The ID of the template that this script is backing.

from_template_id : integer

The ID of the template this script uses, if any.

template_dependents_count : integer

How many other scripts use this one as a template.

template_script_name : string

The name of the template script.

links : dict::

details : string

The details link to get more information about the script.
runs : string

The runs link to get the run information list for this script.

schedule : dict::

scheduled : boolean

If the item 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.

running_as : dict::

id : integer

The ID of this user.
name : string

This user’s name.
username : string

This user’s username.
initials : string

This user’s initials.
online : boolean

Whether this user is online.

next_run_at : string/time

The time of the next scheduled run.

time_zone : string

The time zone of this script.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

hidden : boolean

The hidden status of the item.

target_project_id : integer

Target project to which script outputs will be added.

archived : string

The archival status of the requested item(s).

sql : string

The raw SQL query for the script.

expanded_arguments : dict

Expanded arguments for use in injecting into different environments.

remote_host_id : integer

The remote host ID that this script will connect to.

credential_id : integer

The credential that this script will use.

code_preview : string

The code that this script will run with arguments inserted.

csv_settings : dict::

include_header : boolean

Whether or not to include headers in the output data. Default: true
compression : string

The type of compression to use, if any, one of “none”, “zip”, or “gzip”. Default: gzip
column_delimiter : string

Which delimiter to use, one of “comma”, “tab”, or “pipe”. Default: comma
unquoted : boolean

Whether or not to quote fields. Default: false
force_multifile : boolean

Whether or not the csv should be split into multiple files. Default: false
filename_prefix : string

A user specified filename prefix for the output file to have. Default: null
max_file_size : integer

The max file size, in MB, created files will be. Only available when force_multifile is true.

put_sql_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_sql_projects(self, id, project_id)¶

Add a SQL script to a project

Parameters:	id : integer The ID of the SQL script. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_sql_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_sql_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Search¶

class Search(session_kwargs, client, return_type='civis')¶

Methods

`list`(self, \*[, query, type, offset, order, …])	Perform a search
`list_types`(self)	List available search types

list(self, *, query='DEFAULT', type='DEFAULT', offset='DEFAULT', order='DEFAULT', owner='DEFAULT', limit='DEFAULT', archived='DEFAULT', last_run_state='DEFAULT')¶

Perform a search

Parameters:

query : string, optional: The search query.
type : string, optional: The type for the search. It accepts a comma-separated list. Valid arguments are listed on the “GET /search/types” endpoint.
offset : integer, optional: The offset for the search results.
order : string, optional: The field on which to order the result set.
owner : string, optional: The owner for the search.
limit : integer, optional: Defaults to 10. Maximum allowed is 1000.
archived : string, optional: If specified, return only results with the chosen archived status; either ‘true’, ‘false’, or ‘all’. Defaults to ‘false’.
last_run_state : string, optional: The last run state of the job being searched for; either: ‘queued’, ‘running’, ‘succeeded’, ‘failed’, or ‘cancelled’.

Returns:

total_results : integer

The number of items matching the search query.

aggregations : dict

Aggregations by owner and type for the search results.

results : list::

The items returned by the search. - score : number/float

The relevance score from the search request.

type : string

The type of the item.
id : integer

The ID of the item.
name : string

The name of the item.
type_name : string

The verbose name of the type.
updated_at : string/time

The time the item was last updated.
owner : string

The owner of the item.
use_count : integer

The use count of the item, if the item is a template.
last_run_id : integer

The last run id of the item, if the item is a job.
last_run_state : string

The last run state of the item, if the item is a job.
last_run_start : string/time

The last run start time of the item, if the item is a job.
last_run_finish : string/time

The last run finish time of the item, if the item is a job.
public : boolean

The flag that indicates a template is available to all users.
last_run_exception : string

The exception of the item after the last run, if the item is a job.

list_types(self)¶

List available search types

Returns:	type : string The name of the item type.

Services¶

class Services(session_kwargs, client, return_type='civis')¶

Methods

`delete_deployments`(self, service_id, …)	Delete a Service deployment
`delete_projects`(self, id, project_id)	Remove a Service from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_tokens`(self, id, token_id)	Revoke a token by id
`get`(self, id)	Get a Service
`get_deployments`(self, service_id, deployment_id)	Get details about a Service deployment
`list`(self, \*[, hidden, archived, author, …])	List Services
`list_deployments`(self, service_id, \*[, …])	List deployments for a Service
`list_deployments_logs`(self, id, …[, …])	Get the logs for a Service deployment
`list_projects`(self, id, \*[, hidden])	List the projects a Service belongs to
`list_shares`(self, id)	List users and groups permissioned on this object
`list_tokens`(self, id)	List tokens
`patch`(self, id, \*[, name, description, …])	Update some attributes of this Service
`post`(self, \*[, name, description, type, …])	Create a Service
`post_clone`(self, id)	Clone this Service
`post_deployments`(self, service_id, \*[, …])	Deploy a Service
`post_redeploy`(self, service_id, \*[, …])	Redeploy a Service
`post_tokens`(self, id, name, \*[, machine_token])	Create a new long-lived service token
`put`(self, id, \*[, name, description, …])	Replace all attributes of this Service
`put_archive`(self, id, status)	Update the archive status of this object
`put_projects`(self, id, project_id)	Add a Service to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_deployments(self, service_id, deployment_id)¶

Delete a Service deployment

Parameters:	service_id : integer The ID of the owning Service deployment_id : integer The ID for this deployment
Returns:	None Response code 204: success

delete_projects(self, id, project_id)¶

Remove a Service from a project

Parameters:	id : integer The ID of the Service. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_tokens(self, id, token_id)¶

Revoke a token by id

Parameters:	id : integer The ID of the service. token_id : integer The ID of the token.
Returns:	None Response code 204: success

get(self, id)¶

Get a Service

Parameters:

id : integer

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

get_deployments(self, service_id, deployment_id)¶

Get details about a Service deployment

Parameters:

service_id : integer: The ID of the owning Service
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: A signed URL for viewing the deployed item.
instance_type : string: The EC2 instance type requested for the deployment.
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
service_id : integer: The ID of owning Service

list(self, *, hidden='DEFAULT', archived='DEFAULT', author='DEFAULT', status='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Services

Parameters:

hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(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 Services with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘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 Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

created_at : string/time

updated_at : string/time

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

current_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).
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

archived : string

The archival status of the requested item(s).

list_deployments(self, service_id, *, deployment_id='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List deployments for a Service

Parameters:

service_id : integer: The ID of the owning Service
deployment_id : integer, optional: The ID for this deployment
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional: Page number of the results to return. Defaults to the first page, 1.
order : string, optional: The field on which to order the result set. Defaults to created_at. Must be one of: created_at.
order_dir : string, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional: If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:

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).
instance_type : string: The EC2 instance type requested for the deployment.
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
service_id : integer: The ID of owning Service

list_deployments_logs(self, id, deployment_id, *, start_at='DEFAULT', end_at='DEFAULT', limit='DEFAULT')¶

Get the logs for a Service deployment

Parameters:	id : integer The ID of the owning Service. deployment_id : integer The ID for this deployment. start_at : string, optional Log entries with a lower timestamp will be omitted. end_at : string, optional Log entries with a higher timestamp will be omitted. limit : integer, optional The maximum number of log messages to return. Default of 10000.
Returns:	message : string The log message. stream : string The stream of the log. One of “stdout”, “stderr”. created_at : string/date-time The time the log was created. source : string The source of the log. One of “system”, “user”.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Service belongs to

Parameters:

id : integer: The ID of the Service.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_tokens(self, id)¶

List tokens

Parameters:

id : integer: The ID of the service.

Returns:

id : integer

The ID of the token.

name : string

The name of the token.

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.

machine_token : boolean

If true, this token is not tied to a particular user.

created_at : string/time

The date and time when the token was created.

patch(self, id, *, name='DEFAULT', description='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', schedule='DEFAULT', replicas='DEFAULT', max_replicas='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', api_key_id='DEFAULT', permission_set_id='DEFAULT', git_repo_url='DEFAULT', git_repo_ref='DEFAULT', git_path_dir='DEFAULT', environment_variables='DEFAULT', notifications='DEFAULT', partition_label='DEFAULT')¶

Update some attributes of this Service

Parameters:

id : integer

The ID for this Service.

name : string, optional

The name of this Service.

description : string, optional

The description of this Service.

docker_image_name : string, optional

The name of the docker image to pull from DockerHub.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub (default: latest).

schedule : dict, optional::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

replicas : integer, optional

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer, optional

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string, optional

The EC2 instance type to deploy to.

memory : integer, optional

The amount of memory allocated to each replica of the Service.

cpu : integer, optional

The amount of cpu allocated to each replica of the the Service.

credentials : list, optional

A list of credential IDs to pass to the Service.

api_key_id : integer, optional

API key id of user

permission_set_id : integer, optional

The ID of the associated permission set, if any.

git_repo_url : string, optional

The url for the git repo where the Service code lives.

git_repo_ref : string, optional

The git reference to use when pulling code from the repo.

git_path_dir : string, optional

The path to the Service code within the git repo. If unspecified, the root directory will be used.

environment_variables : dict, optional

Environment Variables to be passed into the Service.

notifications : dict, optional::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string, optional

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

post(self, *, name='DEFAULT', description='DEFAULT', type='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', schedule='DEFAULT', replicas='DEFAULT', max_replicas='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', api_key_id='DEFAULT', permission_set_id='DEFAULT', git_repo_url='DEFAULT', git_repo_ref='DEFAULT', git_path_dir='DEFAULT', environment_variables='DEFAULT', notifications='DEFAULT', partition_label='DEFAULT', hidden='DEFAULT')¶

Create a Service

Parameters:

name : string, optional

The name of this Service.

description : string, optional

The description of this Service.

type : string, optional

The type of this Service

docker_image_name : string, optional

The name of the docker image to pull from DockerHub.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub (default: latest).

schedule : dict, optional::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

replicas : integer, optional

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer, optional

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string, optional

The EC2 instance type to deploy to.

memory : integer, optional

The amount of memory allocated to each replica of the Service.

cpu : integer, optional

The amount of cpu allocated to each replica of the the Service.

credentials : list, optional

A list of credential IDs to pass to the Service.

api_key_id : integer, optional

API key id of user

permission_set_id : integer, optional

The ID of the associated permission set, if any.

git_repo_url : string, optional

The url for the git repo where the Service code lives.

git_repo_ref : string, optional

The git reference to use when pulling code from the repo.

git_path_dir : string, optional

The path to the Service code within the git repo. If unspecified, the root directory will be used.

environment_variables : dict, optional

Environment Variables to be passed into the Service.

notifications : dict, optional::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string, optional

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

hidden : boolean, optional

The hidden status of the item.

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

post_clone(self, id)¶

Clone this Service

Parameters:

id : integer

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

post_deployments(self, service_id, *, deployment_id='DEFAULT')¶

Deploy a Service

Parameters:

service_id : integer: The ID of the owning Service
deployment_id : integer, optional: 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: A signed URL for viewing the deployed item.
instance_type : string: The EC2 instance type requested for the deployment.
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
service_id : integer: The ID of owning Service

post_redeploy(self, service_id, *, deployment_id='DEFAULT')¶

Redeploy a Service

Parameters:

service_id : integer: The ID of the owning Service
deployment_id : integer, optional: 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: A signed URL for viewing the deployed item.
instance_type : string: The EC2 instance type requested for the deployment.
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
service_id : integer: The ID of owning Service

post_tokens(self, id, name, *, machine_token='DEFAULT')¶

Create a new long-lived service token

Parameters:

id : integer: The ID of the service.
name : string: The name of the token.
machine_token : boolean, optional: If true, create a compact token with no user information.

Returns:

id : integer

The ID of the token.

name : string

The name of the token.

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.

machine_token : boolean

If true, this token is not tied to a particular user.

created_at : string/time

The date and time when the token was created.

token : string

The value of the token. Only returned when the token is first created.

put(self, id, *, name='DEFAULT', description='DEFAULT', docker_image_name='DEFAULT', docker_image_tag='DEFAULT', schedule='DEFAULT', replicas='DEFAULT', max_replicas='DEFAULT', instance_type='DEFAULT', memory='DEFAULT', cpu='DEFAULT', credentials='DEFAULT', api_key_id='DEFAULT', permission_set_id='DEFAULT', git_repo_url='DEFAULT', git_repo_ref='DEFAULT', git_path_dir='DEFAULT', environment_variables='DEFAULT', notifications='DEFAULT', partition_label='DEFAULT')¶

Replace all attributes of this Service

Parameters:

id : integer

The ID for this Service.

name : string, optional

The name of this Service.

description : string, optional

The description of this Service.

docker_image_name : string, optional

The name of the docker image to pull from DockerHub.

docker_image_tag : string, optional

The tag of the docker image to pull from DockerHub (default: latest).

schedule : dict, optional::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

replicas : integer, optional

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer, optional

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string, optional

The EC2 instance type to deploy to.

memory : integer, optional

The amount of memory allocated to each replica of the Service.

cpu : integer, optional

The amount of cpu allocated to each replica of the the Service.

credentials : list, optional

A list of credential IDs to pass to the Service.

api_key_id : integer, optional

API key id of user

permission_set_id : integer, optional

The ID of the associated permission set, if any.

git_repo_url : string, optional

The url for the git repo where the Service code lives.

git_repo_ref : string, optional

The git reference to use when pulling code from the repo.

git_path_dir : string, optional

The path to the Service code within the git repo. If unspecified, the root directory will be used.

environment_variables : dict, optional

Environment Variables to be passed into the Service.

notifications : dict, optional::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string, optional

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

put_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID for this Service.

name : string

The name of this Service.

description : string

The description of this Service.

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.

type : string

The type of this Service

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).

schedule : dict::

runtime_plan : string

Only affects the service when deployed. On Demand means that the service will be turned on when viewed and automatically turned off after periods of inactivity. Specific Times means the service will be on when scheduled. Always On means the deployed service will always be on.
recurrences : list::
List of day-hour combinations this item is scheduled for - scheduled_days : list

Days it is scheduled on, based on numeric value starting at 0 for Sunday
- scheduled_hours : list
  
  Hours it is scheduled on

time_zone : string

replicas : integer

The number of Service replicas to deploy. When maxReplicas is set, this field defines the minimum number of replicas to deploy.

max_replicas : integer

The maximum number of Service replicas to deploy. Defining this field enables autoscaling.

instance_type : string

The EC2 instance type to deploy to.

memory : integer

The amount of memory allocated to each replica of the Service.

cpu : integer

The amount of cpu allocated to each replica of the the Service.

created_at : string/time

updated_at : string/time

credentials : list

A list of credential IDs to pass to the Service.

api_key_id : integer

API key id of user

permission_set_id : integer

The ID of the associated permission set, if any.

git_repo_url : string

The url for the git repo where the Service code lives.

git_repo_ref : string

The git reference to use when pulling code from the repo.

git_path_dir : string

The path to the Service code within the git repo. If unspecified, the root directory will be used.

report_id : integer

The ID of the associated report.

current_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

A signed URL for viewing the deployed item.
instance_type : string

The EC2 instance type requested for the deployment.
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
service_id : integer

The ID of owning Service

current_url : string

The URL that the service is hosted at.

environment_variables : dict

Environment Variables to be passed into the Service.

notifications : dict::

failure_email_addresses : list

Addresses to notify by e-mail when the service fails.
failure_on : boolean

If failure email notifications are on

partition_label : string

The partition label used to run this object. Only settable with custom_partitions feature flag. Beware attribute may break or change in the future.

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

put_projects(self, id, project_id)¶

Add a Service to a project

Parameters:	id : integer The ID of the Service. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Storage_Hosts¶

civis.resources._resources.Storage_Hosts¶: alias of civis.resources._resources.StorageHosts

Tables¶

class Tables(session_kwargs, client, return_type='civis')¶

Methods

`delete_projects`(self, id, project_id)	Remove a Table from a project
`get`(self, id)	Show basic table info
`get_enhancements_cass_ncoa`(self, id, …)	Deprecation warning!
`get_enhancements_geocodings`(self, id, …)	Deprecation warning!
`list`(self, \*[, database_id, schema, name, …])	List tables
`list_columns`(self, id, \*[, name, limit, …])	List columns in the specified table
`list_projects`(self, id, \*[, hidden])	List the projects a Table belongs to
`patch`(self, id, \*[, ontology_mapping, …])	Update a table
`post_enhancements_cass_ncoa`(self, …[, …])	Deprecation warning!
`post_enhancements_geocodings`(self, …)	Deprecation warning!
`post_refresh`(self, id)	Deprecation warning!
`post_scan`(self, database_id, schema, …[, …])	Creates and enqueues a single table scanner job on a new table
`put_projects`(self, id, project_id)	Add a Table to a project

delete_projects(self, id, project_id)¶

Remove a Table from a project

Parameters:	id : integer The ID of the Table. project_id : integer The ID of the project.
Returns:	None Response code 204: success

get(self, id)¶

Show basic table info

Parameters:

id : integer

Returns:

id : integer

The ID of the table.

database_id : integer

The ID of the database.

schema : string

The name of the schema containing the table.

name : string

Name of the table.

description : string

The description of the table, as specified by the table owner

is_view : boolean

True if this table represents a view. False if it represents a regular table.

row_count : integer

The number of rows in the table.

column_count : integer

The number of columns in the table.

size_mb : number/float

The size of the table in megabytes.

owner : string

The database username of the table’s owner.

distkey : string

The column used as the Amazon Redshift distkey.

sortkeys : string

The column used as the Amazon Redshift sortkey.

refresh_status : string

How up-to-date the table’s statistics on row counts, null counts, distinct counts, and values distributions are. One of: refreshing, stale, or current.

last_refresh : string/date-time

The time of the last statistics refresh.

data_updated_at : string/date-time

The last time that Civis Platform captured a change in this table.Only applicable for Redshift tables; please see the Civis help desk for more info.

schema_updated_at : string/date-time

The last time that Civis Platform captured a change to the table attributes/structure.Only applicable for Redshift tables; please see the Civis help desk for more info.

refresh_id : string

The ID of the most recent statistics refresh.

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.

primary_keys : list

The primary keys for this table.

last_modified_keys : list

The columns indicating an entry’s modification status for this table.

ontology_mapping : dict

The ontology-key to column-name mapping. See /ontology for the list of valid ontology keys.

columns : list::

name : string

Name of the column.
civis_data_type : string

The generic data type of the column (ex. “string”). Since this is database-agnostic, it may be helpful when loading data to R/Python.
sql_type : string

The database-specific SQL type of the column (ex. “varchar(30)”).
sample_values : list

A sample of values from the column.
encoding : string

The compression encoding for this columnSee: http://docs.aws.amazon.com /redshift/latest/dg/c_Compression_encodings.html
description : string

The description of the column, as specified by the table owner
order : integer

Relative position of the column in the table.
min_value : string

Smallest value in the column.
max_value : string

Largest value in the column.
avg_value : number/float

Average value of the column, where applicable.
stddev : number/float

Stddev of the column, where applicable.
value_distribution_percent : dict

A mapping between each value in the column and the percentage of rows with that value.Only present for tables with fewer than approximately 25,000,000 rows and for columns with fewer than twenty distinct values.
coverage_count : integer

Number of non-null values in the column.
null_count : integer

Number of null values in the column.
possible_dependent_variable_types : list

Possible dependent variable types the column may be used to model. Null if it may not be used as a dependent variable.
useable_as_independent_variable : boolean

Whether the column may be used as an independent variable to train a model.
useable_as_primary_key : boolean

Whether the column may be used as an primary key to identify table rows.
value_distribution : dict

An object mapping distinct values in the column to the number of times they appear in the column
distinct_count : integer

Number of distinct values in the column.

joins : list::

id : integer
left_table_id : integer
left_identifier : string
right_table_id : integer
right_identifier : string
on : string
left_join : boolean
created_at : string/time
updated_at : string/time

multipart_key : list

enhancements : list::

type : string
created_at : string/time
updated_at : string/time
join_id : integer

view_def : string

table_def : string

outgoing_table_matches : list::

source_table_id : integer

Source table
target_type : string

Target type
target_id : integer

Target ID
target : dict::
- name : string
job : dict::
- id : integer
- name : string
- type : string
- from_template_id : integer
- 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 item.
- match_options : dict::
  
  max_matches : integer
  
  threshold : string

get_enhancements_cass_ncoa(self, id, source_table_id)¶

Warning: The tables/:source_table_id/enhancements/cass-ncoa/:id endpoint is deprecated and will be removed after January 1, 2021. View the status of a CASS / NCOA table enhancement

Parameters:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.

Returns:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.
state : string: The state of the enhancement, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
enhanced_table_schema : string: The schema name of the table created by the enhancement.
enhanced_table_name : string: The name of the table created by the enhancement.
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.

get_enhancements_geocodings(self, id, source_table_id)¶

Warning: The tables/:source_table_id/enhancements/geocodings/:id endpoint is deprecated and will be removed after January 1, 2021. View the status of a geocoding table enhancement

Parameters:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.

Returns:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.
state : string: The state of the enhancement, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
enhanced_table_schema : string: The schema name of the table created by the enhancement.
enhanced_table_name : string: The name of the table created by the enhancement.

list(self, *, database_id='DEFAULT', schema='DEFAULT', name='DEFAULT', search='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List tables

Parameters:

database_id : integer, optional: The ID of the database.
schema : string, optional: If specified, will be used to filter the tables returned. Substring matching is supported with “%” and “*” wildcards (e.g., “schema=%census%” will return both “client_census.table” and “census_2010.table”).
name : string, optional: If specified, will be used to filter the tables returned. Substring matching is supported with “%” and “*” wildcards (e.g., “name=%table%” will return both “table1” and “my table”).
search : string, optional: If specified, will be used to filter the tables returned. Will search across schema and name (in the full form schema.name) and will return any full name containing the search string.
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 schema. Must be one of: schema, name, search.
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 the table.

database_id : integer

The ID of the database.

schema : string

The name of the schema containing the table.

name : string

Name of the table.

description : string

The description of the table, as specified by the table owner

is_view : boolean

True if this table represents a view. False if it represents a regular table.

row_count : integer

The number of rows in the table.

column_count : integer

The number of columns in the table.

size_mb : number/float

The size of the table in megabytes.

owner : string

The database username of the table’s owner.

distkey : string

The column used as the Amazon Redshift distkey.

sortkeys : string

The column used as the Amazon Redshift sortkey.

refresh_status : string

How up-to-date the table’s statistics on row counts, null counts, distinct counts, and values distributions are. One of: refreshing, stale, or current.

last_refresh : string/date-time

The time of the last statistics refresh.

refresh_id : string

The ID of the most recent statistics refresh.

last_run : dict::

id : integer
state : string
created_at : string/time

The time that the run was queued.
started_at : string/time

The time that the run started.
finished_at : string/time

The time that the run completed.
error : string

The error message for this run, if present.

list_columns(self, id, *, name='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List columns in the specified table

Parameters:

id : integer
name : string, optional: Search for columns with the given name, within the specified table.
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 name. Must be one of: name, order.
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:

name : string: Name of the column.
civis_data_type : string: The generic data type of the column (ex. “string”). Since this is database- agnostic, it may be helpful when loading data to R/Python.
sql_type : string: The database-specific SQL type of the column (ex. “varchar(30)”).
sample_values : list: A sample of values from the column.
encoding : string: The compression encoding for this columnSee: http://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html
description : string: The description of the column, as specified by the table owner
order : integer: Relative position of the column in the table.
min_value : string: Smallest value in the column.
max_value : string: Largest value in the column.
avg_value : number/float: Average value of the column, where applicable.
stddev : number/float: Stddev of the column, where applicable.
value_distribution_percent : dict: A mapping between each value in the column and the percentage of rows with that value.Only present for tables with fewer than approximately 25,000,000 rows and for columns with fewer than twenty distinct values.
coverage_count : integer: Number of non-null values in the column.
null_count : integer: Number of null values in the column.
possible_dependent_variable_types : list: Possible dependent variable types the column may be used to model. Null if it may not be used as a dependent variable.
useable_as_independent_variable : boolean: Whether the column may be used as an independent variable to train a model.
useable_as_primary_key : boolean: Whether the column may be used as an primary key to identify table rows.
value_distribution : dict: An object mapping distinct values in the column to the number of times they appear in the column
distinct_count : integer: Number of distinct values in the column.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Table belongs to

Parameters:

id : integer: The ID of the Table.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

patch(self, id, *, ontology_mapping='DEFAULT', description='DEFAULT', primary_keys='DEFAULT', last_modified_keys='DEFAULT')¶

Update a table

Parameters:

id : integer: The ID of the table.
ontology_mapping : dict, optional: The ontology-key to column-name mapping. See /ontology for the list of valid ontology keys.
description : string, optional: The user-defined description of the table.
primary_keys : list, optional: A list of column(s) which together uniquely identify a row in the data.These columns must not contain NULL values.
last_modified_keys : list, optional: The columns indicating when a row was last modified.

Returns:

id : integer

The ID of the table.

database_id : integer

The ID of the database.

schema : string

The name of the schema containing the table.

name : string

Name of the table.

description : string

The description of the table, as specified by the table owner

is_view : boolean

True if this table represents a view. False if it represents a regular table.

row_count : integer

The number of rows in the table.

column_count : integer

The number of columns in the table.

size_mb : number/float

The size of the table in megabytes.

owner : string

The database username of the table’s owner.

distkey : string

The column used as the Amazon Redshift distkey.

sortkeys : string

The column used as the Amazon Redshift sortkey.

refresh_status : string

How up-to-date the table’s statistics on row counts, null counts, distinct counts, and values distributions are. One of: refreshing, stale, or current.

last_refresh : string/date-time

The time of the last statistics refresh.

data_updated_at : string/date-time

The last time that Civis Platform captured a change in this table.Only applicable for Redshift tables; please see the Civis help desk for more info.

schema_updated_at : string/date-time

The last time that Civis Platform captured a change to the table attributes/structure.Only applicable for Redshift tables; please see the Civis help desk for more info.

refresh_id : string

The ID of the most recent statistics refresh.

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.

primary_keys : list

The primary keys for this table.

last_modified_keys : list

The columns indicating an entry’s modification status for this table.

ontology_mapping : dict

The ontology-key to column-name mapping. See /ontology for the list of valid ontology keys.

post_enhancements_cass_ncoa(self, source_table_id, *, perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT')¶

Warning: The tables/:source_table_id/enhancements/cass-ncoa endpoint is deprecated and will be removed after January 1, 2021. Standardize addresses in a table

Parameters:

source_table_id : integer: The ID of the table to be enhanced.
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.

Returns:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.
state : string: The state of the enhancement, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
enhanced_table_schema : string: The schema name of the table created by the enhancement.
enhanced_table_name : string: The name of the table created by the enhancement.
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.

post_enhancements_geocodings(self, source_table_id)¶

Warning: The tables/:source_table_id/enhancements/geocodings endpoint is deprecated and will be removed after January 1, 2021. Geocode a table

Parameters:

source_table_id : integer: The ID of the table to be enhanced.

Returns:

id : integer: The ID of the enhancement.
source_table_id : integer: The ID of the table that was enhanced.
state : string: The state of the enhancement, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
enhanced_table_schema : string: The schema name of the table created by the enhancement.
enhanced_table_name : string: The name of the table created by the enhancement.

post_refresh(self, id)¶

Warning: The tables/:id/refresh endpoint is deprecated. Please use tables/scan from now on. Request a refresh for column and table statistics

Parameters:

id : integer

Returns:

id : integer

The ID of the table.

database_id : integer

The ID of the database.

schema : string

The name of the schema containing the table.

name : string

Name of the table.

description : string

The description of the table, as specified by the table owner

is_view : boolean

True if this table represents a view. False if it represents a regular table.

row_count : integer

The number of rows in the table.

column_count : integer

The number of columns in the table.

size_mb : number/float

The size of the table in megabytes.

owner : string

The database username of the table’s owner.

distkey : string

The column used as the Amazon Redshift distkey.

sortkeys : string

The column used as the Amazon Redshift sortkey.

refresh_status : string

How up-to-date the table’s statistics on row counts, null counts, distinct counts, and values distributions are. One of: refreshing, stale, or current.

last_refresh : string/date-time

The time of the last statistics refresh.

data_updated_at : string/date-time

The last time that Civis Platform captured a change in this table.Only applicable for Redshift tables; please see the Civis help desk for more info.

schema_updated_at : string/date-time

The last time that Civis Platform captured a change to the table attributes/structure.Only applicable for Redshift tables; please see the Civis help desk for more info.

refresh_id : string

The ID of the most recent statistics refresh.

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.

primary_keys : list

The primary keys for this table.

last_modified_keys : list

The columns indicating an entry’s modification status for this table.

ontology_mapping : dict

The ontology-key to column-name mapping. See /ontology for the list of valid ontology keys.

columns : list::

name : string

Name of the column.
civis_data_type : string

The generic data type of the column (ex. “string”). Since this is database-agnostic, it may be helpful when loading data to R/Python.
sql_type : string

The database-specific SQL type of the column (ex. “varchar(30)”).
sample_values : list

A sample of values from the column.
encoding : string

The compression encoding for this columnSee: http://docs.aws.amazon.com /redshift/latest/dg/c_Compression_encodings.html
description : string

The description of the column, as specified by the table owner
order : integer

Relative position of the column in the table.
min_value : string

Smallest value in the column.
max_value : string

Largest value in the column.
avg_value : number/float

Average value of the column, where applicable.
stddev : number/float

Stddev of the column, where applicable.
value_distribution_percent : dict

A mapping between each value in the column and the percentage of rows with that value.Only present for tables with fewer than approximately 25,000,000 rows and for columns with fewer than twenty distinct values.
coverage_count : integer

Number of non-null values in the column.
null_count : integer

Number of null values in the column.
possible_dependent_variable_types : list

Possible dependent variable types the column may be used to model. Null if it may not be used as a dependent variable.
useable_as_independent_variable : boolean

Whether the column may be used as an independent variable to train a model.
useable_as_primary_key : boolean

Whether the column may be used as an primary key to identify table rows.
value_distribution : dict

An object mapping distinct values in the column to the number of times they appear in the column
distinct_count : integer

Number of distinct values in the column.

joins : list::

id : integer
left_table_id : integer
left_identifier : string
right_table_id : integer
right_identifier : string
on : string
left_join : boolean
created_at : string/time
updated_at : string/time

multipart_key : list

enhancements : list::

type : string
created_at : string/time
updated_at : string/time
join_id : integer

view_def : string

table_def : string

outgoing_table_matches : list::

source_table_id : integer

Source table
target_type : string

Target type
target_id : integer

Target ID
target : dict::
- name : string
job : dict::
- id : integer
- name : string
- type : string
- from_template_id : integer
- 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 item.
- match_options : dict::
  
  max_matches : integer
  
  threshold : string

post_scan(self, database_id, schema, table_name, *, stats_priority='DEFAULT')¶

Creates and enqueues a single table scanner job on a new table

Parameters:

database_id : integer: The ID of the database.
schema : string: The name of the schema containing the table.
table_name : string: The name of the table.
stats_priority : string, optional: When to sync table statistics. Valid Options are the following. Option: ‘flag’ means to flag stats for the next scheduled run of a full table scan on the database. Option: ‘block’ means to block this job on stats syncing. Option: ‘queue’ means to queue a separate job for syncing stats and do not block this job on the queued job. Defaults to ‘flag’

Returns:

job_id : integer: The ID of the job created.
run_id : integer: The ID of the run created.

put_projects(self, id, project_id)¶

Add a Table to a project

Parameters:	id : integer The ID of the Table. project_id : integer The ID of the project.
Returns:	None Response code 204: success

Templates¶

class Templates(session_kwargs, client, return_type='civis')¶

Methods

`delete_reports_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_reports_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`delete_scripts_projects`(self, id, project_id)	Remove a Script Template from a project
`delete_scripts_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_scripts_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get_reports`(self, id)	Get a Report Template
`get_scripts`(self, id)	Get a Script Template
`list_reports`(self, \*[, hidden, category, …])	List Report Templates
`list_reports_shares`(self, id)	List users and groups permissioned on this object
`list_scripts`(self, \*[, hidden, category, …])	List Script Templates
`list_scripts_projects`(self, id, \*[, hidden])	List the projects a Script Template belongs to
`list_scripts_shares`(self, id)	List users and groups permissioned on this object
`patch_reports`(self, id, \*[, name, …])	Update some attributes of this Report Template
`patch_scripts`(self, id, \*[, name, note, …])	Update some attributes of this Script Template
`post_reports`(self, name, code_body, \*[, …])	Create a Report Template
`post_reports_review`(self, id, status)	Review a template for security vulnerability and correctness (admin-only)
`post_scripts`(self, script_id, name, \*[, …])	Create a Script Template
`post_scripts_review`(self, id, status)	Review a template for security vulnerability and correctness (admin-only)
`put_reports`(self, id, name, code_body, \*[, …])	Replace all attributes of this Report Template
`put_reports_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_reports_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object
`put_scripts`(self, id, name, \*[, note, …])	Replace all attributes of this Script Template
`put_scripts_projects`(self, id, project_id)	Add a Script Template to a project
`put_scripts_shares_groups`(self, id, …[, …])	Set the permissions groups has on this object
`put_scripts_shares_users`(self, id, user_ids, …)	Set the permissions users have on this object

delete_reports_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_reports_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

delete_scripts_projects(self, id, project_id)¶

Remove a Script Template from a project

Parameters:	id : integer The ID of the Script Template. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_scripts_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_scripts_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get_reports(self, id)¶

Get a Report Template

Parameters:

id : integer

Returns:

id : integer

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

auth_code_url : string

A URL to the template’s stored code body.

provide_api_key : boolean

Whether reports based on this template request an API Key from the report viewer.

hidden : boolean

The hidden status of the item.

get_scripts(self, id)¶

Get a Script Template

Parameters:

id : integer

Returns:

id : integer
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
script_type : string: The type of the template’s backing script (e.g SQL, Container, Python, R, JavaScript)
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
note : string: A note describing what this template is used for; custom scripts created off this template will display this description.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.
hidden : boolean: The hidden status of the item.

list_reports(self, *, hidden='DEFAULT', category='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Report Templates

Parameters:

hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
category : string, optional: A category to filter results by, one of: dataset-viz
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, updated_at, 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

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

list_reports_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_scripts(self, *, hidden='DEFAULT', category='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Script Templates

Parameters:

hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
category : string, optional: A category to filter results by, one of: import, export, enhancement, model, and script
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, updated_at, 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
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.

list_scripts_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Script Template belongs to

Parameters:

id : integer: The ID of the Script Template.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_scripts_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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_reports(self, id, *, name='DEFAULT', category='DEFAULT', archived='DEFAULT', code_body='DEFAULT', provide_api_key='DEFAULT')¶

Update some attributes of this Report Template

Parameters:

id : integer
name : string, optional: The name of the template.
category : string, optional: The category of this report template. Can be left blank. Acceptable values are: dataset-viz
archived : boolean, optional: Whether the template has been archived.
code_body : string, optional: The code for the Template body.
provide_api_key : boolean, optional: Whether reports based on this template request an API Key from the report viewer.

Returns:

id : integer

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

auth_code_url : string

A URL to the template’s stored code body.

provide_api_key : boolean

Whether reports based on this template request an API Key from the report viewer.

hidden : boolean

The hidden status of the item.

patch_scripts(self, id, *, name='DEFAULT', note='DEFAULT', ui_report_id='DEFAULT', archived='DEFAULT')¶

Update some attributes of this Script Template

Parameters:

id : integer
name : string, optional: The name of the template.
note : string, optional: A note describing what this template is used for; custom scripts created off this template will display this description.
ui_report_id : integer, optional: The id of the report that this template uses.
archived : boolean, optional: Whether the template has been archived.

Returns:

id : integer
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
script_type : string: The type of the template’s backing script (e.g SQL, Container, Python, R, JavaScript)
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
note : string: A note describing what this template is used for; custom scripts created off this template will display this description.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.
hidden : boolean: The hidden status of the item.

post_reports(self, name, code_body, *, category='DEFAULT', archived='DEFAULT', provide_api_key='DEFAULT', hidden='DEFAULT')¶

Create a Report Template

Parameters:

name : string: The name of the template.
code_body : string: The code for the Template body.
category : string, optional: The category of this report template. Can be left blank. Acceptable values are: dataset-viz
archived : boolean, optional: Whether the template has been archived.
provide_api_key : boolean, optional: Whether reports based on this template request an API Key from the report viewer.
hidden : boolean, optional: The hidden status of the item.

Returns:

id : integer

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

auth_code_url : string

A URL to the template’s stored code body.

provide_api_key : boolean

Whether reports based on this template request an API Key from the report viewer.

hidden : boolean

The hidden status of the item.

post_reports_review(self, id, status)¶

Review a template for security vulnerability and correctness (admin-only)

Parameters:

id : integer: The ID of the item.
status : boolean: Whether this item has been reviewed.

Returns:

id : integer

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

auth_code_url : string

A URL to the template’s stored code body.

provide_api_key : boolean

Whether reports based on this template request an API Key from the report viewer.

hidden : boolean

The hidden status of the item.

post_scripts(self, script_id, name, *, note='DEFAULT', ui_report_id='DEFAULT', archived='DEFAULT', hidden='DEFAULT')¶

Create a Script Template

Parameters:

script_id : integer: The id of the script that this template uses.
name : string: The name of the template.
note : string, optional: A note describing what this template is used for; custom scripts created off this template will display this description.
ui_report_id : integer, optional: The id of the report that this template uses.
archived : boolean, optional: Whether the template has been archived.
hidden : boolean, optional: The hidden status of the item.

Returns:

id : integer
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
script_type : string: The type of the template’s backing script (e.g SQL, Container, Python, R, JavaScript)
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
note : string: A note describing what this template is used for; custom scripts created off this template will display this description.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.
hidden : boolean: The hidden status of the item.

post_scripts_review(self, id, status)¶

Review a template for security vulnerability and correctness (admin-only)

Parameters:

id : integer: The ID of the item.
status : boolean: Whether this item has been reviewed.

Returns:

id : integer
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
script_type : string: The type of the template’s backing script (e.g SQL, Container, Python, R, JavaScript)
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
note : string: A note describing what this template is used for; custom scripts created off this template will display this description.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.
hidden : boolean: The hidden status of the item.

put_reports(self, id, name, code_body, *, category='DEFAULT', archived='DEFAULT', provide_api_key='DEFAULT')¶

Replace all attributes of this Report Template

Parameters:

id : integer
name : string: The name of the template.
code_body : string: The code for the Template body.
category : string, optional: The category of this report template. Can be left blank. Acceptable values are: dataset-viz
archived : boolean, optional: Whether the template has been archived.
provide_api_key : boolean, optional: Whether reports based on this template request an API Key from the report viewer.

Returns:

id : integer

name : string

The name of the template.

category : string

The category of this report template. Can be left blank. Acceptable values are: dataset-viz

created_at : string/time

updated_at : string/time

use_count : integer

The number of uses of this template.

archived : boolean

Whether the template has been archived.

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.

tech_reviewed : boolean

Whether this template has been audited by Civis for security vulnerability and correctness.

auth_code_url : string

A URL to the template’s stored code body.

provide_api_key : boolean

Whether reports based on this template request an API Key from the report viewer.

hidden : boolean

The hidden status of the item.

put_reports_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_reports_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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_scripts(self, id, name, *, note='DEFAULT', ui_report_id='DEFAULT', archived='DEFAULT')¶

Replace all attributes of this Script Template

Parameters:

id : integer
name : string: The name of the template.
note : string, optional: A note describing what this template is used for; custom scripts created off this template will display this description.
ui_report_id : integer, optional: The id of the report that this template uses.
archived : boolean, optional: Whether the template has been archived.

Returns:

id : integer
public : boolean: If the template is public or not.
script_id : integer: The id of the script that this template uses.
script_type : string: The type of the template’s backing script (e.g SQL, Container, Python, R, JavaScript)
user_context : string: The user context of the script that this template uses.
name : string: The name of the template.
category : string: The category of this template.
note : string: A note describing what this template is used for; custom scripts created off this template will display this description.
created_at : string/time
updated_at : string/time
use_count : integer: The number of uses of this template.
ui_report_id : integer: The id of the report that this template uses.
tech_reviewed : boolean: Whether this template has been audited by Civis for security vulnerability and correctness.
archived : boolean: Whether the template has been archived.
hidden : boolean: The hidden status of the item.

put_scripts_projects(self, id, project_id)¶

Add a Script Template to a project

Parameters:	id : integer The ID of the Script Template. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_scripts_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_scripts_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.

Users¶

class Users(session_kwargs, client, return_type='civis')¶

Methods

`delete_api_keys`(self, id, key_id)	Revoke the specified API key
`delete_me_favorites`(self, id)	Unfavorite an item
`delete_sessions`(self, id)	Terminate all of the user’s active sessions (must be an admin or client user admin)
`get`(self, id)	Show info about a user
`get_api_keys`(self, id, key_id)	Show the specified API key
`list`(self, \*[, feature_flag, …])	List users
`list_api_keys`(self, id, \*[, limit, …])	Show API keys belonging to the specified user
`list_me`(self)	Show info about the logged-in user
`list_me_favorites`(self, \*[, object_id, …])	List Favorites
`list_me_ui`(self)	UI configuration for logged-in user
`patch`(self, id, \*[, name, email, active, …])	Update info about a user (must be an admin or client user admin)
`patch_me`(self, \*[, preferences, …])	Update info about the logged-in user
`post`(self, name, email, primary_group_id, …)	Create a new user (must be an admin or client user admin)
`post_api_keys`(self, id, expires_in, name, \*)	Create a new API key belonging to the logged-in user
`post_me_favorites`(self, object_id, object_type)	Favorite an item

delete_api_keys(self, id, key_id)¶

Revoke the specified API key

Parameters:

id : string: The ID of the user or ‘me’.
key_id : integer: The ID of the API key.

Returns:

id : integer

The ID of the API key.

name : string

The name of the API key.

expires_at : string/date-time

The date and time when the key expired.

created_at : string/date-time

The date and time when the key was created.

revoked_at : string/date-time

The date and time when the key was revoked.

last_used_at : string/date-time

The date and time when the key was last used.

scopes : list

The scopes which the key is permissioned on.

use_count : integer

The number of times the key has been used.

expired : boolean

True if the key has expired.

active : boolean

True if the key has neither expired nor been revoked.

constraints : list::

Constraints on the abilities of the created key - constraint : string

The path matcher of the constraint.

constraint_type : string

The type of constraint (exact/prefix/regex/verb).
get_allowed : boolean

Whether the constraint allows GET requests.
head_allowed : boolean

Whether the constraint allows HEAD requests.
post_allowed : boolean

Whether the constraint allows POST requests.
put_allowed : boolean

Whether the constraint allows PUT requests.
patch_allowed : boolean

Whether the constraint allows PATCH requests.
delete_allowed : boolean

Whether the constraint allows DELETE requests.

delete_me_favorites(self, id)¶

Unfavorite an item

Parameters:	id : integer The id of the favorite.
Returns:	None Response code 204: success

delete_sessions(self, id)¶

Terminate all of the user’s active sessions (must be an admin or client user admin)

Parameters:

id : integer: The ID of this user.

Returns:

id : integer

The ID of this user.

user : string

The username of this user.

name : string

The name of this user.

email : string

The email of this user.

active : boolean

The account status of this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

city : string

The city of this user.

state : string

The state of this user.

time_zone : string

The time zone of this user.

initials : string

The initials of this user.

department : string

The department of this user.

title : string

The title of this user.

github_username : string

The GitHub username of this user.

prefers_sms_otp : boolean

The preference for phone authorization of this user

vpn_enabled : boolean

The availability of vpn for this user.

sso_disabled : boolean

The availability of SSO for this user.

otp_required_for_login : boolean

The two factor authentication requirement for this user.

exempt_from_org_sms_otp_disabled : boolean

Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.

sms_otp_allowed : boolean

Whether the user is allowed to receive two factor authentication codes via SMS.

robot : boolean

Whether the user is a robot.

phone : string

The phone number of this user.

organization_slug : string

The slug of the organization the user belongs to.

organization_sso_disable_capable : boolean

The user’s organization’s ability to disable sso for their users.

organization_login_type : string

The user’s organization’s login type.

organization_sms_otp_disabled : boolean

Whether the user’s organization has SMS OTP disabled.

get(self, id)¶

Show info about a user

Parameters:

id : integer: The ID of this user.

Returns:

id : integer

The ID of this user.

user : string

The username of this user.

name : string

The name of this user.

email : string

The email of this user.

active : boolean

The account status of this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

city : string

The city of this user.

state : string

The state of this user.

time_zone : string

The time zone of this user.

initials : string

The initials of this user.

department : string

The department of this user.

title : string

The title of this user.

github_username : string

The GitHub username of this user.

prefers_sms_otp : boolean

The preference for phone authorization of this user

vpn_enabled : boolean

The availability of vpn for this user.

sso_disabled : boolean

The availability of SSO for this user.

otp_required_for_login : boolean

The two factor authentication requirement for this user.

exempt_from_org_sms_otp_disabled : boolean

Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.

sms_otp_allowed : boolean

Whether the user is allowed to receive two factor authentication codes via SMS.

robot : boolean

Whether the user is a robot.

phone : string

The phone number of this user.

organization_slug : string

The slug of the organization the user belongs to.

organization_sso_disable_capable : boolean

The user’s organization’s ability to disable sso for their users.

organization_login_type : string

The user’s organization’s login type.

organization_sms_otp_disabled : boolean

Whether the user’s organization has SMS OTP disabled.

get_api_keys(self, id, key_id)¶

Show the specified API key

Parameters:

id : string: The ID of the user or ‘me’.
key_id : integer: The ID of the API key.

Returns:

id : integer

The ID of the API key.

name : string

The name of the API key.

expires_at : string/date-time

The date and time when the key expired.

created_at : string/date-time

The date and time when the key was created.

revoked_at : string/date-time

The date and time when the key was revoked.

last_used_at : string/date-time

The date and time when the key was last used.

scopes : list

The scopes which the key is permissioned on.

use_count : integer

The number of times the key has been used.

expired : boolean

True if the key has expired.

active : boolean

True if the key has neither expired nor been revoked.

constraints : list::

Constraints on the abilities of the created key - constraint : string

The path matcher of the constraint.

constraint_type : string

The type of constraint (exact/prefix/regex/verb).
get_allowed : boolean

Whether the constraint allows GET requests.
head_allowed : boolean

Whether the constraint allows HEAD requests.
post_allowed : boolean

Whether the constraint allows POST requests.
put_allowed : boolean

Whether the constraint allows PUT requests.
patch_allowed : boolean

Whether the constraint allows PATCH requests.
delete_allowed : boolean

Whether the constraint allows DELETE requests.

list(self, *, feature_flag='DEFAULT', account_status='DEFAULT', query='DEFAULT', group_id='DEFAULT', organization_id='DEFAULT', exclude_groups='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List users

Parameters:

feature_flag : string, optional: Return users that have a feature flag enabled.
account_status : string, optional: The account status by which to filter users. May be one of “active”, “inactive”, or “all”.
query : string, optional: Return users who match the given query, based on name, user, and email.
group_id : integer, optional: The ID of the group by which to filter users. Cannot be present if organization_id is.
organization_id : integer, optional: The ID of the organization by which to filter users. Cannot be present if group_id is.
exclude_groups : boolean, optional: Whether or to exclude users’ groups. Default: false.
limit : integer, optional: Number of results to return. Defaults to 20. Maximum allowed is 10000.
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, user.
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 user.

user : string

The username of this user.

name : string

The name of this user.

email : string

The email of this user.

active : boolean

The account status of this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

created_at : string/date-time

The date and time when the user was created.

current_sign_in_at : string/date-time

The date and time when the user’s current session began.

list_api_keys(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

Show API keys belonging to the specified user

Parameters:

id : string: The ID of the user or ‘me’.
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.
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 API key.
name : string: The name of the API key.
expires_at : string/date-time: The date and time when the key expired.
created_at : string/date-time: The date and time when the key was created.
revoked_at : string/date-time: The date and time when the key was revoked.
last_used_at : string/date-time: The date and time when the key was last used.
scopes : list: The scopes which the key is permissioned on.
use_count : integer: The number of times the key has been used.
expired : boolean: True if the key has expired.
active : boolean: True if the key has neither expired nor been revoked.
constraint_count : integer: The number of constraints on the created key

list_me(self)¶

Show info about the logged-in user

Returns:

id : integer

The ID of this user.

name : string

This user’s name.

email : string

This user’s email address.

username : string

This user’s username.

initials : string

This user’s initials.

last_checked_announcements : string/date-time

The date and time at which the user last checked their announcements.

feature_flags : dict

The feature flag settings for this user.

roles : list

The roles this user has, listed by slug.

preferences : dict

This user’s preferences.

custom_branding : string

The branding of Platform for this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

organization_name : string

The name of the organization the user belongs to.

organization_slug : string

The slug of the organization the user belongs to.

organization_default_theme_id : integer

The ID of the organizations’s default theme.

created_at : string/date-time

The date and time when the user was created.

sign_in_count : integer

The number of times the user has signed in.

assuming_role : boolean

Whether the user is assuming a role or not.

assuming_admin : boolean

Whether the user is assuming admin.

assuming_admin_expiration : string/date-time

When the user’s admin role is set to expire.

list_me_favorites(self, *, object_id='DEFAULT', object_type='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Favorites

Parameters:

object_id : integer, optional: The id of the object. If specified as a query parameter, must also specify object_type parameter.
object_type : string, optional: The type of the object that is favorited. Valid options: Project
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 created_at. Must be one of: created_at, object_type, object_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 favorite.
object_id : integer: The id of the object. If specified as a query parameter, must also specify object_type parameter.
object_type : string: The type of the object that is favorited. Valid options: Project
object_name : string: The name of the object that is favorited.
created_at : string/time: The time this favorite was created.

list_me_ui(self)¶

UI configuration for logged-in user

Returns:

id : integer

The ID of this user.

navigation_menus : dict

Navigation menus visible to this user.

user_menus : dict

User profile menu items available to this user.

user_type : dict::

vendor : boolean

This attribute is deprecated
media : boolean

True if user has access to the Media Optimizer job type.
main_app : string

This attribute is deprecated
app_count : integer

This attribute is deprecated
reports_only : boolean

True if user is a reports-only user.
reports_creator : boolean

True if this user is allowed to create HTML reports.

zendesk_token : string

JSON web token for this user’s Zendesk widget.

patch(self, id, *, name='DEFAULT', email='DEFAULT', active='DEFAULT', primary_group_id='DEFAULT', city='DEFAULT', state='DEFAULT', time_zone='DEFAULT', initials='DEFAULT', department='DEFAULT', title='DEFAULT', prefers_sms_otp='DEFAULT', group_ids='DEFAULT', vpn_enabled='DEFAULT', sso_disabled='DEFAULT', otp_required_for_login='DEFAULT', exempt_from_org_sms_otp_disabled='DEFAULT', robot='DEFAULT', phone='DEFAULT', password='DEFAULT')¶

Update info about a user (must be an admin or client user admin)

Parameters:

id : integer: The ID of this user.
name : string, optional: The name of this user.
email : string, optional: The email of this user.
active : boolean, optional: The account status of this user.
primary_group_id : integer, optional: The ID of the primary group of this user.
city : string, optional: The city of this user.
state : string, optional: The state of this user.
time_zone : string, optional: The time zone of this user.
initials : string, optional: The initials of this user.
department : string, optional: The department of this user.
title : string, optional: The title of this user.
prefers_sms_otp : boolean, optional: The preference for phone authorization of this user
group_ids : list, optional: An array of ids of all the groups this user is in.
vpn_enabled : boolean, optional: The availability of vpn for this user.
sso_disabled : boolean, optional: The availability of SSO for this user.
otp_required_for_login : boolean, optional: The two factor authentication requirement for this user.
exempt_from_org_sms_otp_disabled : boolean, optional: Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.
robot : boolean, optional: Whether the user is a robot.
phone : string, optional: The phone number of this user.
password : string, optional: The password of this user.

Returns:

id : integer

The ID of this user.

user : string

The username of this user.

name : string

The name of this user.

email : string

The email of this user.

active : boolean

The account status of this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

city : string

The city of this user.

state : string

The state of this user.

time_zone : string

The time zone of this user.

initials : string

The initials of this user.

department : string

The department of this user.

title : string

The title of this user.

github_username : string

The GitHub username of this user.

prefers_sms_otp : boolean

The preference for phone authorization of this user

vpn_enabled : boolean

The availability of vpn for this user.

sso_disabled : boolean

The availability of SSO for this user.

otp_required_for_login : boolean

The two factor authentication requirement for this user.

exempt_from_org_sms_otp_disabled : boolean

Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.

sms_otp_allowed : boolean

Whether the user is allowed to receive two factor authentication codes via SMS.

robot : boolean

Whether the user is a robot.

phone : string

The phone number of this user.

organization_slug : string

The slug of the organization the user belongs to.

organization_sso_disable_capable : boolean

The user’s organization’s ability to disable sso for their users.

organization_login_type : string

The user’s organization’s login type.

organization_sms_otp_disabled : boolean

Whether the user’s organization has SMS OTP disabled.

patch_me(self, *, preferences='DEFAULT', last_checked_announcements='DEFAULT')¶

Update info about the logged-in user

Parameters:

preferences : dict, optional::

app_index_order_field : string

This attribute is deprecated
app_index_order_dir : string

This attribute is deprecated
result_index_order_field : string

Order field for the results index page.
result_index_order_dir : string

Order direction for the results index page.
result_index_type_filter : string

Type filter for the results index page.
result_index_author_filter : string

Author filter for the results index page.
result_index_archived_filter : string

Archived filter for the results index page.
import_index_order_field : string

Order field for the imports index page.
import_index_order_dir : string

Order direction for the imports index page.
import_index_type_filter : string

Type filter for the imports index page.
import_index_author_filter : string

Author filter for the imports index page.
import_index_dest_filter : string

Destination filter for the imports index page.
import_index_status_filter : string

Status filter for the imports index page.
import_index_archived_filter : string

Archived filter for the imports index page.
export_index_order_field : string

Order field for the exports index page.
export_index_order_dir : string

Order direction for the exports index page.
export_index_type_filter : string

Type filter for the exports index page.
export_index_author_filter : string

Author filter for the exports index page.
export_index_status_filter : string

Status filter for the exports index page.
model_index_order_field : string

Order field for the models index page.
model_index_order_dir : string

Order direction for the models index page.
model_index_author_filter : string

Author filter for the models index page.
model_index_status_filter : string

Status filter for the models index page.
model_index_archived_filter : string

Archived filter for the models index page.
model_index_thumbnail_view : string

Thumbnail view for the models index page.
script_index_order_field : string

Order field for the scripts index page.
script_index_order_dir : string

Order direction for the scripts index page.
script_index_type_filter : string

Type filter for the scripts index page.
script_index_author_filter : string

Author filter for the scripts index page.
script_index_status_filter : string

Status filter for the scripts index page.
script_index_archived_filter : string

Archived filter for the scripts index page.
project_index_order_field : string

Order field for the projects index page.
project_index_order_dir : string

Order direction for the projects index page.
project_index_author_filter : string

Author filter for the projects index page.
project_index_archived_filter : string

Archived filter for the projects index page.
report_index_thumbnail_view : string

Thumbnail view for the reports index page.
project_detail_order_field : string

Order field for projects detail pages.
project_detail_order_dir : string

Order direction for projects detail pages.
project_detail_author_filter : string

Author filter for projects detail pages.
project_detail_type_filter : string

Type filter for projects detail pages.
project_detail_archived_filter : string

Archived filter for the projects detail pages.
enhancement_index_order_field : string

Order field for the enhancements index page.
enhancement_index_order_dir : string

Order direction for the enhancements index page.
enhancement_index_author_filter : string

Author filter for the enhancements index page.
enhancement_index_archived_filter : string

Archived filter for the enhancements index page.
preferred_server_id : integer

ID of preferred server.
civis_explore_skip_intro : boolean

Whether the user is shown steps for each exploration.
registration_index_order_field : string

Order field for the registrations index page.
registration_index_order_dir : string

Order direction for the registrations index page.
registration_index_status_filter : string

Status filter for the registrations index page.
upgrade_requested : string

Whether a free trial upgrade has been requested.
welcome_order_field : string

Order direction for the welcome page.
welcome_order_dir : string

Order direction for the welcome page.
welcome_author_filter : string

Status filter for the welcome page.
welcome_status_filter : string

Status filter for the welcome page.
welcome_archived_filter : string

Status filter for the welcome page.
data_pane_width : string

Width of the data pane when expanded.
data_pane_collapsed : string

Whether the data pane is collapsed.
notebook_order_field : string

Order field for the notebooks page.
notebook_order_dir : string

Order direction for the notebooks page.
notebook_author_filter : string

Author filter for the notebooks page.
notebook_archived_filter : string

Archived filter for the notebooks page.
notebook_status_filter : string

Status filter for the notebooks page.
workflow_index_order_field : string

Order field for the workflows page.
workflow_index_order_dir : string

Order direction for the workflows page.
workflow_index_author_filter : string

Author filter for the workflows page.
workflow_index_archived_filter : string

Archived filter for the workflows page.
service_order_field : string

Order field for the services page.
service_order_dir : string

Order direction for the services page.
service_author_filter : string

Author filter for the services page.
service_archived_filter : string

Archived filter for the services page.

last_checked_announcements : string/date-time, optional

The date and time at which the user last checked their announcements.

Returns:

id : integer

The ID of this user.

name : string

This user’s name.

email : string

This user’s email address.

username : string

This user’s username.

initials : string

This user’s initials.

last_checked_announcements : string/date-time

The date and time at which the user last checked their announcements.

feature_flags : dict

The feature flag settings for this user.

roles : list

The roles this user has, listed by slug.

preferences : dict

This user’s preferences.

custom_branding : string

The branding of Platform for this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

organization_name : string

The name of the organization the user belongs to.

organization_slug : string

The slug of the organization the user belongs to.

organization_default_theme_id : integer

The ID of the organizations’s default theme.

created_at : string/date-time

The date and time when the user was created.

sign_in_count : integer

The number of times the user has signed in.

assuming_role : boolean

Whether the user is assuming a role or not.

assuming_admin : boolean

Whether the user is assuming admin.

assuming_admin_expiration : string/date-time

When the user’s admin role is set to expire.

post(self, name, email, primary_group_id, user, *, active='DEFAULT', city='DEFAULT', state='DEFAULT', time_zone='DEFAULT', initials='DEFAULT', department='DEFAULT', title='DEFAULT', prefers_sms_otp='DEFAULT', group_ids='DEFAULT', vpn_enabled='DEFAULT', sso_disabled='DEFAULT', otp_required_for_login='DEFAULT', exempt_from_org_sms_otp_disabled='DEFAULT', robot='DEFAULT', send_email='DEFAULT')¶

Create a new user (must be an admin or client user admin)

Parameters:

name : string: The name of this user.
email : string: The email of this user.
primary_group_id : integer: The ID of the primary group of this user.
user : string: The username of this user.
active : boolean, optional: The account status of this user.
city : string, optional: The city of this user.
state : string, optional: The state of this user.
time_zone : string, optional: The time zone of this user.
initials : string, optional: The initials of this user.
department : string, optional: The department of this user.
title : string, optional: The title of this user.
prefers_sms_otp : boolean, optional: The preference for phone authorization of this user
group_ids : list, optional: An array of ids of all the groups this user is in.
vpn_enabled : boolean, optional: The availability of vpn for this user.
sso_disabled : boolean, optional: The availability of SSO for this user.
otp_required_for_login : boolean, optional: The two factor authentication requirement for this user.
exempt_from_org_sms_otp_disabled : boolean, optional: Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.
robot : boolean, optional: Whether the user is a robot.
send_email : boolean, optional: Whether the user will receive a welcome email.

Returns:

id : integer

The ID of this user.

user : string

The username of this user.

name : string

The name of this user.

email : string

The email of this user.

active : boolean

The account status of this user.

primary_group_id : integer

The ID of the primary group of this user.

groups : list::

An array of all the groups this user is in. - id : integer

The ID of this group.

name : string

The name of this group.
organization_id : integer

The organization associated with this group.

city : string

The city of this user.

state : string

The state of this user.

time_zone : string

The time zone of this user.

initials : string

The initials of this user.

department : string

The department of this user.

title : string

The title of this user.

github_username : string

The GitHub username of this user.

prefers_sms_otp : boolean

The preference for phone authorization of this user

vpn_enabled : boolean

The availability of vpn for this user.

sso_disabled : boolean

The availability of SSO for this user.

otp_required_for_login : boolean

The two factor authentication requirement for this user.

exempt_from_org_sms_otp_disabled : boolean

Whether the user has SMS OTP enabled on an individual level. This field does not matter if the org does not have SMS OTP disabled.

sms_otp_allowed : boolean

Whether the user is allowed to receive two factor authentication codes via SMS.

robot : boolean

Whether the user is a robot.

phone : string

The phone number of this user.

organization_slug : string

The slug of the organization the user belongs to.

organization_sso_disable_capable : boolean

The user’s organization’s ability to disable sso for their users.

organization_login_type : string

The user’s organization’s login type.

organization_sms_otp_disabled : boolean

Whether the user’s organization has SMS OTP disabled.

post_api_keys(self, id, expires_in, name, *, constraints='DEFAULT')¶

Create a new API key belonging to the logged-in user

Parameters:

id : string

The ID of the user or ‘me’.

expires_in : integer

The number of seconds the key should last for.

name : string

The name of the API key.

constraints : list, optional::

Constraints on the abilities of the created key. - constraint : string

The path matcher of the constraint.

constraint_type : string

The type of constraint (exact/prefix/regex/verb).
get_allowed : boolean

Whether the constraint allows GET requests.
head_allowed : boolean

Whether the constraint allows HEAD requests.
post_allowed : boolean

Whether the constraint allows POST requests.
put_allowed : boolean

Whether the constraint allows PUT requests.
patch_allowed : boolean

Whether the constraint allows PATCH requests.
delete_allowed : boolean

Whether the constraint allows DELETE requests.

Returns:

id : integer

The ID of the API key.

name : string

The name of the API key.

expires_at : string/date-time

The date and time when the key expired.

created_at : string/date-time

The date and time when the key was created.

revoked_at : string/date-time

The date and time when the key was revoked.

last_used_at : string/date-time

The date and time when the key was last used.

scopes : list

The scopes which the key is permissioned on.

use_count : integer

The number of times the key has been used.

expired : boolean

True if the key has expired.

active : boolean

True if the key has neither expired nor been revoked.

constraints : list::

Constraints on the abilities of the created key - constraint : string

The path matcher of the constraint.

constraint_type : string

The type of constraint (exact/prefix/regex/verb).
get_allowed : boolean

Whether the constraint allows GET requests.
head_allowed : boolean

Whether the constraint allows HEAD requests.
post_allowed : boolean

Whether the constraint allows POST requests.
put_allowed : boolean

Whether the constraint allows PUT requests.
patch_allowed : boolean

Whether the constraint allows PATCH requests.
delete_allowed : boolean

Whether the constraint allows DELETE requests.

token : string

The API key.

post_me_favorites(self, object_id, object_type)¶

Favorite an item

Parameters:	object_id : integer The id of the object. If specified as a query parameter, must also specify object_type parameter. object_type : string The type of the object that is favorited. Valid options: Project
Returns:	id : integer The id of the favorite. object_id : integer The id of the object. If specified as a query parameter, must also specify object_type parameter. object_type : string The type of the object that is favorited. Valid options: Project object_name : string The name of the object that is favorited. created_at : string/time The time this favorite was created.

Workflows¶

class Workflows(session_kwargs, client, return_type='civis')¶

Methods

`delete_projects`(self, id, project_id)	Remove a Workflow from a project
`delete_shares_groups`(self, id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(self, id, user_id)	Revoke the permissions a user has on this object
`get`(self, id)	Get a Workflow
`get_executions`(self, id, execution_id)	Get a workflow execution
`get_executions_tasks`(self, id, execution_id, …)	Get a task of a workflow execution
`get_git_commits`(self, id, commit_hash)	Get file contents at commit_hash
`list`(self, \*[, hidden, archived, author, …])	List Workflows
`list_executions`(self, id, \*[, limit, …])	List workflow executions
`list_git`(self, id)	Get the git metadata attached to an item
`list_git_commits`(self, id)	Get the git commits for an item
`list_projects`(self, id, \*[, hidden])	List the projects a Workflow belongs to
`list_shares`(self, id)	List users and groups permissioned on this object
`patch`(self, id, \*[, name, description, …])	Update some attributes of this Workflow
`patch_git`(self, id, \*[, git_ref, …])	Update an attached git file
`post`(self, name, \*[, description, …])	Create a Workflow
`post_clone`(self, id, \*[, clone_schedule, …])	Clone this Workflow
`post_executions`(self, id, \*[, target_task, …])	Execute a workflow
`post_executions_cancel`(self, id, execution_id)	Cancel a workflow execution
`post_executions_resume`(self, id, execution_id)	Resume a paused workflow execution
`post_executions_retry`(self, id, execution_id, \*)	Retry a failed task, or all failed tasks in an execution
`post_git_commits`(self, id, content, message, …)	Commit and push a new version of the file
`put`(self, id, name, \*[, description, …])	Replace all attributes of this Workflow
`put_archive`(self, id, status)	Update the archive status of this object
`put_git`(self, id, \*[, git_ref, git_branch, …])	Attach an item to a file in a git repo
`put_projects`(self, id, project_id)	Add a Workflow to a project
`put_shares_groups`(self, id, group_ids, …)	Set the permissions groups has on this object
`put_shares_users`(self, id, user_ids, …[, …])	Set the permissions users have on this object

delete_projects(self, id, project_id)¶

Remove a Workflow from a project

Parameters:	id : integer The ID of the Workflow. project_id : integer The ID of the project.
Returns:	None Response code 204: success

delete_shares_groups(self, id, group_id)¶

Revoke the permissions a group has on this object

Parameters:	id : integer The ID of the resource that is shared. group_id : integer The ID of the group.
Returns:	None Response code 204: success

delete_shares_users(self, id, user_id)¶

Revoke the permissions a user has on this object

Parameters:	id : integer The ID of the resource that is shared. user_id : integer The ID of the user.
Returns:	None Response code 204: success

get(self, id)¶

Get a Workflow

Parameters:

id : integer

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

get_executions(self, id, execution_id)¶

Get a workflow execution

Parameters:

id : integer: The ID for the workflow.
execution_id : integer: The ID for the workflow execution.

Returns:

id : integer

The ID for this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

definition : string

The definition of the workflow for this execution.

input : dict

Key-value pairs defined for this execution.

included_tasks : list

The subset of workflow tasks selected to execute.

tasks : list::

The tasks associated with this execution. - name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled
mistral_state_info : string

Extra info associated with the state of the task.
runs : list::
The runs associated with this task, in descending order by id. - id : integer

The ID of the run.
- job_id : integer
  
  The ID of the job associated with the run.
- state : string
  
  The state of the run.
executions : list::
The executions run by this task, in descending order by id. - id : integer

The ID of the execution.
- workflow_id : integer
  
  The ID of the workflow associated with the execution.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

get_executions_tasks(self, id, execution_id, task_name)¶

Get a task of a workflow execution

Parameters:

id : integer: The ID for the workflow.
execution_id : integer: The ID for the workflow execution.
task_name : string: The URL-encoded name of the task.

Returns:

name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled

mistral_state_info : string

Extra info associated with the state of the task.

runs : list::

The runs associated with this task, in descending order by id. - id : integer

The ID of the run.

job_id : integer

The ID of the job associated with the run.
state : string

The state of the run.
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.

executions : list::

The executions run by this task, in descending order by id. - id : integer

The ID of the execution.

workflow_id : integer

The ID of the workflow associated with the execution.
state : string

The state of this workflow execution.
created_at : string/time

The time this execution was created.
started_at : string/time

The time this execution started.
finished_at : string/time

The time this execution finished.

get_git_commits(self, id, commit_hash)¶

Get file contents at commit_hash

Parameters:	id : integer The ID of the file. commit_hash : string The SHA (full or shortened) of the desired git commit.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

list(self, *, hidden='DEFAULT', archived='DEFAULT', author='DEFAULT', state='DEFAULT', scheduled='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List Workflows

Parameters:

hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
archived : string, optional: The archival status of the requested item(s).
author : string, optional: Author of the workflow. It accepts a comma-separated list of author ids.
state : array, optional: State of the most recent execution.One or more of queued, running, succeeded, failed, cancelled, idle, and scheduled.
scheduled : boolean, optional: If the workflow is scheduled.
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 workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

valid : boolean

The validity of the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

archived : string

The archival status of the requested item(s).

created_at : string/time

updated_at : string/time

list_executions(self, id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶

List workflow executions

Parameters:

id : integer: The ID for this workflow.
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 id. Must be one of: id, 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 this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

list_git(self, id)¶

Get the git metadata attached to an item

Parameters:

id : integer: The ID of the file.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

list_git_commits(self, id)¶

Get the git commits for an item

Parameters:	id : integer The ID of the file.
Returns:	commit_hash : string The SHA of the commit. author_name : string The name of the commit’s author. date : string/time The commit’s timestamp. message : string The commit message.

list_projects(self, id, *, hidden='DEFAULT')¶

List the projects a Workflow belongs to

Parameters:

id : integer: The ID of the Workflow.
hidden : boolean, optional: If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

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 item(s).

list_shares(self, id)¶

List users and groups permissioned on this object

Parameters:

id : integer: The ID of the resource that is shared.

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(self, id, *, name='DEFAULT', description='DEFAULT', definition='DEFAULT', schedule='DEFAULT', allow_concurrent_executions='DEFAULT', time_zone='DEFAULT', notifications='DEFAULT')¶

Update some attributes of this Workflow

Parameters:

id : integer

The ID for this workflow.

name : string, optional

The name of this workflow.

description : string, optional

A description of the workflow.

definition : string, optional

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

schedule : dict, optional::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean, optional

Whether the workflow can execute when already running.

time_zone : string, optional

The time zone of this workflow.

notifications : dict, optional::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

patch_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Update an attached git file

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

post(self, name, *, description='DEFAULT', from_job_chain='DEFAULT', definition='DEFAULT', schedule='DEFAULT', allow_concurrent_executions='DEFAULT', time_zone='DEFAULT', notifications='DEFAULT', hidden='DEFAULT')¶

Create a Workflow

Parameters:

name : string

The name of this workflow.

description : string, optional

A description of the workflow.

from_job_chain : integer, optional

If specified, create a workflow from the job chain this job is in, and inherit the schedule from the root of the chain.

definition : string, optional

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

schedule : dict, optional::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean, optional

Whether the workflow can execute when already running.

time_zone : string, optional

The time zone of this workflow.

notifications : dict, optional::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

hidden : boolean, optional

The hidden status of the item.

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

post_clone(self, id, *, clone_schedule='DEFAULT', clone_notifications='DEFAULT')¶

Clone this Workflow

Parameters:

id : integer: The ID for the workflow.
clone_schedule : boolean, optional: If true, also copy the schedule to the new workflow.
clone_notifications : boolean, optional: If true, also copy the notifications to the new workflow.

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

post_executions(self, id, *, target_task='DEFAULT', input='DEFAULT', included_tasks='DEFAULT')¶

Execute a workflow

Parameters:

id : integer: The ID for the workflow.
target_task : string, optional: For a reverse workflow, the name of the task to target.
input : dict, optional: Key-value pairs to send to this execution as inputs.
included_tasks : list, optional: If specified, executes only the subset of workflow tasks included.

Returns:

id : integer

The ID for this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

definition : string

The definition of the workflow for this execution.

input : dict

Key-value pairs defined for this execution.

included_tasks : list

The subset of workflow tasks selected to execute.

tasks : list::

The tasks associated with this execution. - name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled
mistral_state_info : string

Extra info associated with the state of the task.
runs : list::
The runs associated with this task, in descending order by id. - id : integer

The ID of the run.
- job_id : integer
  
  The ID of the job associated with the run.
- state : string
  
  The state of the run.
executions : list::
The executions run by this task, in descending order by id. - id : integer

The ID of the execution.
- workflow_id : integer
  
  The ID of the workflow associated with the execution.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

post_executions_cancel(self, id, execution_id)¶

Cancel a workflow execution

Parameters:

id : integer: The ID for the workflow.
execution_id : integer: The ID for the workflow execution.

Returns:

id : integer

The ID for this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

definition : string

The definition of the workflow for this execution.

input : dict

Key-value pairs defined for this execution.

included_tasks : list

The subset of workflow tasks selected to execute.

tasks : list::

The tasks associated with this execution. - name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled
mistral_state_info : string

Extra info associated with the state of the task.
runs : list::
The runs associated with this task, in descending order by id. - id : integer

The ID of the run.
- job_id : integer
  
  The ID of the job associated with the run.
- state : string
  
  The state of the run.
executions : list::
The executions run by this task, in descending order by id. - id : integer

The ID of the execution.
- workflow_id : integer
  
  The ID of the workflow associated with the execution.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

post_executions_resume(self, id, execution_id)¶

Resume a paused workflow execution

Parameters:

id : integer: The ID for the workflow.
execution_id : integer: The ID for the workflow execution.

Returns:

id : integer

The ID for this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

definition : string

The definition of the workflow for this execution.

input : dict

Key-value pairs defined for this execution.

included_tasks : list

The subset of workflow tasks selected to execute.

tasks : list::

The tasks associated with this execution. - name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled
mistral_state_info : string

Extra info associated with the state of the task.
runs : list::
The runs associated with this task, in descending order by id. - id : integer

The ID of the run.
- job_id : integer
  
  The ID of the job associated with the run.
- state : string
  
  The state of the run.
executions : list::
The executions run by this task, in descending order by id. - id : integer

The ID of the execution.
- workflow_id : integer
  
  The ID of the workflow associated with the execution.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

post_executions_retry(self, id, execution_id, *, task_name='DEFAULT')¶

Retry a failed task, or all failed tasks in an execution

Parameters:

id : integer: The ID for the workflow.
execution_id : integer: The ID for the workflow execution.
task_name : string, optional: If specified, the name of the task to be retried. If not specified, all failed tasks in the execution will be retried.

Returns:

id : integer

The ID for this workflow execution.

state : string

The state of this workflow execution.

mistral_state : string

The state of this workflow as reported by mistral. One of running, paused, success, error, or cancelled

mistral_state_info : string

The state info of this workflow as reported by mistral.

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.

definition : string

The definition of the workflow for this execution.

input : dict

Key-value pairs defined for this execution.

included_tasks : list

The subset of workflow tasks selected to execute.

tasks : list::

The tasks associated with this execution. - name : string

The name of the task.

mistral_state : string

The state of this task. One of idle, waiting, running, delayed, success, error, or cancelled
mistral_state_info : string

Extra info associated with the state of the task.
runs : list::
The runs associated with this task, in descending order by id. - id : integer

The ID of the run.
- job_id : integer
  
  The ID of the job associated with the run.
- state : string
  
  The state of the run.
executions : list::
The executions run by this task, in descending order by id. - id : integer

The ID of the execution.
- workflow_id : integer
  
  The ID of the workflow associated with the execution.

started_at : string/time

The time this execution started.

finished_at : string/time

The time this execution finished.

created_at : string/time

The time this execution was created.

updated_at : string/time

The time this execution was last updated.

post_git_commits(self, id, content, message, file_hash)¶

Commit and push a new version of the file

Parameters:	id : integer The ID of the file. content : string The contents to commit to the file. message : string A commit message describing the changes being made. file_hash : string The full SHA of the file being replaced.
Returns:	content : string The file’s contents. type : string The file’s type. size : integer The file’s size. file_hash : string The SHA of the file.

put(self, id, name, *, description='DEFAULT', definition='DEFAULT', schedule='DEFAULT', allow_concurrent_executions='DEFAULT', time_zone='DEFAULT', notifications='DEFAULT')¶

Replace all attributes of this Workflow

Parameters:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string, optional

A description of the workflow.

definition : string, optional

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

schedule : dict, optional::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean, optional

Whether the workflow can execute when already running.

time_zone : string, optional

The time zone of this workflow.

notifications : dict, optional::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

put_archive(self, id, status)¶

Update the archive status of this object

Parameters:

id : integer: The ID of the object.
status : boolean: The desired archived status of the object.

Returns:

id : integer

The ID for this workflow.

name : string

The name of this workflow.

description : string

A description of the workflow.

definition : string

The definition of the workflow in YAML format. Must not be specified if fromJobChain is specified.

valid : boolean

The validity of the workflow definition.

validation_errors : string

The errors encountered when validating the workflow definition.

file_id : string

The file id for the s3 file containing the workflow configuration.

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.

state : string

The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.

schedule : dict::

scheduled : boolean

If the item 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.

allow_concurrent_executions : boolean

Whether the workflow can execute when already running.

time_zone : string

The time zone of this workflow.

next_execution_at : string/time

The time of the next scheduled execution.

notifications : dict::

urls : list

URLs to receive a POST request at job completion
success_email_subject : string

Custom subject line for success e-mail.
success_email_body : string

Custom body text for success e-mail, written in Markdown.
success_email_addresses : list

Addresses to notify by e-mail when the job completes successfully.
failure_email_addresses : list

Addresses to notify by e-mail when the job fails.
stall_warning_minutes : integer

Stall warning emails will be sent after this amount of minutes.
success_on : boolean

If success email notifications are on
failure_on : boolean

If failure email notifications are on

archived : string

The archival status of the requested item(s).

hidden : boolean

The hidden status of the item.

created_at : string/time

updated_at : string/time

put_git(self, id, *, git_ref='DEFAULT', git_branch='DEFAULT', git_path='DEFAULT', git_repo_url='DEFAULT', pull_from_git='DEFAULT')¶

Attach an item to a file in a git repo

Parameters:

id : integer: The ID of the file.
git_ref : string, optional: A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.
git_branch : string, optional: The git branch that the file is on.
git_path : string, optional: The path of the file in the repository.
git_repo_url : string, optional: The URL of the git repository.
pull_from_git : boolean, optional: Automatically pull latest commit from git. Only works for scripts.

Returns:

git_ref : string

A git reference specifying an unambiguous version of the file. Can be a branch name, or the full or shortened SHA of a commit.

git_branch : string

The git branch that the file is on.

git_path : string

The path of the file in the repository.

git_repo : dict::

id : integer

The ID for this git repository.
repo_url : string

The URL for this git repository.
created_at : string/time
updated_at : string/time

pull_from_git : boolean

Automatically pull latest commit from git. Only works for scripts.

put_projects(self, id, project_id)¶

Add a Workflow to a project

Parameters:	id : integer The ID of the Workflow. project_id : integer The ID of the project.
Returns:	None Response code 204: success

put_shares_groups(self, id, group_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions groups has on this object

Parameters:

id : integer: The ID of the resource that is 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.

put_shares_users(self, id, user_ids, permission_level, *, share_email_body='DEFAULT', send_shared_email='DEFAULT')¶

Set the permissions users have on this object

Parameters:

id : integer: The ID of the resource that is 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.