Jobs
- class Jobs(session_kwargs, client, return_type='raw')
Methods
delete_projects
(id, project_id)Remove a Job from a project
delete_runs
(id, run_id)Cancel a run
delete_shares_groups
(id, group_id)Revoke the permissions a group has on this object
delete_shares_users
(id, user_id)Revoke the permissions a user has on this object
get
(id)Show basic job info
get_runs
(id, run_id)Check status of a job
list
(*[, state, type, q, permission, ...])List Jobs
list_children
(id)Show nested tree of children that this job triggers
list_dependencies
(id, *[, user_id])List dependent objects for this object
list_parents
(id)Show chain of parents as a list that this job triggers from
list_projects
(id, *[, hidden])List the projects a Job belongs to
list_runs
(id, *[, limit, page_num, order, ...])List runs for the given job
list_runs_logs
(id, run_id, *[, last_id, limit])Get the logs for a run
list_runs_outputs
(id, run_id, *[, limit, ...])List the outputs for a run
list_shares
(id)List users and groups permissioned on this object
list_workflows
(id, *[, archived])List the workflows a job belongs to
post_runs
(id)Run a job
Generate and retrieve trigger email address
put_archive
(id, status)Update the archive status of this object
put_projects
(id, project_id)Add a Job to a project
put_shares_groups
(id, group_ids, ...[, ...])Set the permissions groups has on this object
put_shares_users
(id, user_ids, ...[, ...])Set the permissions users have on this object
put_transfer
(id, user_id, ...[, email_body, ...])Transfer ownership of this object to another user
Examples
>>> import civis >>> client = civis.APIClient() >>> client.jobs.list(...)
- delete_projects(id: int, project_id: int)
Remove a Job from a project
- Parameters:
- idint
The ID of the Job.
- project_idint
The ID of the project.
- Returns:
- None
Response code 204: success
- delete_runs(id: int, run_id: int)
Cancel a run
- Parameters:
- idint
The ID of the Job.
- run_idint
The ID of the Run.
- Returns:
- None
Response code 202: success
Revoke the permissions a group has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- group_idint
The ID of the group.
- Returns:
- None
Response code 204: success
Revoke the permissions a user has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint
The ID of the user.
- Returns:
- None
Response code 204: success
- get(id: int)
Show basic job info
- Parameters:
- idint
The ID for this job.
- Returns:
civis.response.Response
id : int
name : str
type : str
from_template_id : int
- statestr
Whether the job is idle, queued, running, cancelled, or failed.
created_at : str (date-time)
updated_at : str (date-time)
- runsList[dict]
Information about the most recent runs of the job.
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- last_rundict
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- hiddenbool
The hidden status of the item.
- archivedstr
The archival status of the requested item(s).
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
success_email_subject : str
success_email_body : str
running_as_user : str
run_by_user : str
- scheduledict
- scheduledbool
If the item is scheduled.
- scheduled_daysList[int]
Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth
- scheduled_hoursList[int]
Hours of the day it is scheduled on.
- scheduled_minutesList[int]
Minutes of the day it is scheduled on.
- scheduled_runs_per_hourint
Deprecated in favor of scheduled minutes.
- scheduled_days_of_monthList[int]
Days of the month it is scheduled on, mutually exclusive with scheduledDays.
- get_runs(id: int, run_id: int)
Check status of a job
- Parameters:
- idint
The ID of the Job.
- run_idint
The ID of the Run.
- Returns:
civis.response.Response
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- list(*, state: str = None, type: str = None, q: str = None, permission: str = None, scheduled: bool = None, hidden: bool = None, archived: str = None, author: str = None, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None)
List Jobs
- Parameters:
- statestr, 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”).
- typestr, optional
The job’s type. Specify multiple values as a comma-separated list (e.g., “A,B”).
- qstr, optional
Query string to search on the id, name, and job type.
- permissionstr, optional
A permissions string, one of “read”, “write”, or “manage”. Lists only jobs for which the current user has that permission.
- scheduledbool, optional
If the item is scheduled.
- hiddenbool, optional
If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
- archivedstr, optional
The archival status of the requested item(s).
- authorstr, optional
If specified, return items from any of these authors. It accepts a comma- separated list of user IDs.
- limitint, optional
Number of results to return. Defaults to its maximum of 50.
- page_numint, optional
Page number of the results to return. Defaults to the first page, 1.
- orderstr, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at.
- order_dirstr, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
- iteratorbool, 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:
civis.response.PaginatedResponse
id : int
name : str
type : str
from_template_id : int
- statestr
Whether the job is idle, queued, running, cancelled, or failed.
created_at : str (date-time)
updated_at : str (date-time)
- last_rundict
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- archivedstr
The archival status of the requested item(s).
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- scheduledict
- scheduledbool
If the item is scheduled.
- scheduled_daysList[int]
Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth
- scheduled_hoursList[int]
Hours of the day it is scheduled on.
- scheduled_minutesList[int]
Minutes of the day it is scheduled on.
- scheduled_runs_per_hourint
Deprecated in favor of scheduled minutes.
- scheduled_days_of_monthList[int]
Days of the month it is scheduled on, mutually exclusive with scheduledDays.
- list_children(id: int)
Show nested tree of children that this job triggers
- Parameters:
- idint
The ID for this job.
- Returns:
civis.response.Response
id : int
name : str
type : str
from_template_id : int
state : str
created_at : str (date-time)
updated_at : str (date-time)
- runsList[dict]
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- last_rundict
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
children : List[dict]
- list_dependencies(id: int, *, user_id: int = None)
List dependent objects for this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint, optional
ID of target user
- Returns:
civis.response.Response
- object_typestr
Dependent object type
- fco_typestr
Human readable dependent object type
- idint
Dependent object ID
- namestr
Dependent object name, or nil if the requesting user cannot read this object
- permission_levelstr
Permission level of target user (not user’s groups) for dependent object. Null if no target user or not shareable (e.g. a database table).
- descriptionstr
Additional information about the dependency, if relevant
- shareablebool
Whether or not the requesting user can share this object.
- list_parents(id: int)
Show chain of parents as a list that this job triggers from
- Parameters:
- idint
The ID for this job.
- Returns:
civis.response.Response
id : int
name : str
type : str
from_template_id : int
- statestr
Whether the job is idle, queued, running, cancelled, or failed.
created_at : str (date-time)
updated_at : str (date-time)
- runsList[dict]
Information about the most recent runs of the job.
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- last_rundict
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- hiddenbool
The hidden status of the item.
- archivedstr
The archival status of the requested item(s).
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
success_email_subject : str
success_email_body : str
running_as_user : str
run_by_user : str
- scheduledict
- scheduledbool
If the item is scheduled.
- scheduled_daysList[int]
Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth
- scheduled_hoursList[int]
Hours of the day it is scheduled on.
- scheduled_minutesList[int]
Minutes of the day it is scheduled on.
- scheduled_runs_per_hourint
Deprecated in favor of scheduled minutes.
- scheduled_days_of_monthList[int]
Days of the month it is scheduled on, mutually exclusive with scheduledDays.
- list_projects(id: int, *, hidden: bool = None)
List the projects a Job belongs to
- Parameters:
- idint
The ID of the Job.
- hiddenbool, optional
If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.
- Returns:
civis.response.Response
- idint
The ID for this project.
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- namestr
The name of this project.
- descriptionstr
A description of the project.
- usersList[dict]
Users who can see the project.
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
auto_share : bool
created_at : str (time)
updated_at : str (time)
- archivedstr
The archival status of the requested item(s).
- list_runs(id: int, *, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None)
List runs for the given job
- Parameters:
- idint
The ID for this job.
- limitint, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
- page_numint, optional
Page number of the results to return. Defaults to the first page, 1.
- orderstr, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
- order_dirstr, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
- iteratorbool, 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:
civis.response.PaginatedResponse
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- list_runs_logs(id: int, run_id: int, *, last_id: int = None, limit: int = None)
Get the logs for a run
- Parameters:
- idint
The ID of the job job.
- run_idint
The ID of the run.
- last_idint, 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.
- limitint, optional
The maximum number of log messages to return. Default of 10000.
- Returns:
civis.response.Response
- idint
The ID of the log.
- created_atstr (date-time)
The time the log was created.
- messagestr
The log message.
- levelstr
The level of the log. One of unknown,fatal,error,warn,info,debug.
- list_runs_outputs(id: int, run_id: int, *, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None)
List the outputs for a run
- Parameters:
- idint
The ID of the job.
- run_idint
The ID of the run.
- limitint, optional
Number of results to return. Defaults to its maximum of 50.
- page_numint, optional
Page number of the results to return. Defaults to the first page, 1.
- orderstr, optional
The field on which to order the result set. Defaults to created_at. Must be one of: created_at, id.
- order_dirstr, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
- iteratorbool, 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:
civis.response.PaginatedResponse
- object_typestr
The type of the output. Valid values are File, Table, Report, Project, Credential, or JSONValue
- object_idint
The ID of the output.
- namestr
The name of the output.
- linkstr
The hypermedia link to the output.
value : str
List users and groups permissioned on this object
- Parameters:
- idint
The ID of the resource that is shared.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
- list_workflows(id: int, *, archived: str = None)
List the workflows a job belongs to
- Parameters:
- idint
- archivedstr, optional
The archival status of the requested item(s).
- Returns:
civis.response.Response
- idint
The ID for this workflow.
- namestr
The name of this workflow.
- descriptionstr
A description of the workflow.
- validbool
The validity of the workflow definition.
- file_idstr
The file id for the s3 file containing the workflow configuration.
- userdict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- statestr
The state of the workflow. State is “running” if any execution is running, otherwise reflects most recent execution state.
- scheduledict
- scheduledbool
If the item is scheduled.
- scheduled_daysList[int]
Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth
- scheduled_hoursList[int]
Hours of the day it is scheduled on.
- scheduled_minutesList[int]
Minutes of the day it is scheduled on.
- scheduled_runs_per_hourint
Deprecated in favor of scheduled minutes.
- scheduled_days_of_monthList[int]
Days of the month it is scheduled on, mutually exclusive with scheduledDays.
- allow_concurrent_executionsbool
Whether the workflow can execute when already running.
- time_zonestr
The time zone of this workflow.
- next_execution_atstr (time)
The time of the next scheduled execution.
- archivedstr
The archival status of the requested item(s).
created_at : str (time)
updated_at : str (time)
- post_runs(id: int)
Run a job
- Parameters:
- idint
The ID for this job.
- Returns:
civis.response.Response
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- post_trigger_email(id: int)
Generate and retrieve trigger email address
- Parameters:
- idint
The ID for this job.
- Returns:
civis.response.Response
- trigger_emailstr
Email address which may be used to trigger this job to run.
- put_archive(id: int, status: bool)
Update the archive status of this object
- Parameters:
- idint
The ID of the object.
- statusbool
The desired archived status of the object.
- Returns:
civis.response.Response
id : int
name : str
type : str
from_template_id : int
- statestr
Whether the job is idle, queued, running, cancelled, or failed.
created_at : str (date-time)
updated_at : str (date-time)
- runsList[dict]
Information about the most recent runs of the job.
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- last_rundict
id : int
state : str
- created_atstr (time)
The time that the run was queued.
- started_atstr (time)
The time that the run started.
- finished_atstr (time)
The time that the run completed.
- errorstr
The error message for this run, if present.
- hiddenbool
The hidden status of the item.
- archivedstr
The archival status of the requested item(s).
- authordict
- idint
The ID of this user.
- namestr
This user’s name.
- usernamestr
This user’s username.
- initialsstr
This user’s initials.
- onlinebool
Whether this user is online.
- my_permission_levelstr
Your permission level on the object. One of “read”, “write”, or “manage”.
success_email_subject : str
success_email_body : str
running_as_user : str
run_by_user : str
- scheduledict
- scheduledbool
If the item is scheduled.
- scheduled_daysList[int]
Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth
- scheduled_hoursList[int]
Hours of the day it is scheduled on.
- scheduled_minutesList[int]
Minutes of the day it is scheduled on.
- scheduled_runs_per_hourint
Deprecated in favor of scheduled minutes.
- scheduled_days_of_monthList[int]
Days of the month it is scheduled on, mutually exclusive with scheduledDays.
- put_projects(id: int, project_id: int)
Add a Job to a project
- Parameters:
- idint
The ID of the Job.
- project_idint
The ID of the project.
- Returns:
- None
Response code 204: success
Set the permissions groups has on this object
- Parameters:
- idint
The ID of the resource that is shared.
- group_idsList[int]
An array of one or more group IDs.
- permission_levelstr
Options are: “read”, “write”, or “manage”.
- share_email_bodystr, optional
Custom body text for e-mail sent on a share.
- send_shared_emailbool, optional
Send email to the recipients of a share.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
- Parameters:
- idint
The ID of the resource that is shared.
- user_idsList[int]
An array of one or more user IDs.
- permission_levelstr
Options are: “read”, “write”, or “manage”.
- share_email_bodystr, optional
Custom body text for e-mail sent on a share.
- send_shared_emailbool, optional
Send email to the recipients of a share.
- Returns:
civis.response.Response
- readersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- writersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- ownersdict
- usersList[dict]
id : int
name : str
- groupsList[dict]
id : int
name : str
- total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
- total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
- put_transfer(id: int, user_id: int, include_dependencies: bool, *, email_body: str = None, send_email: bool = None)
Transfer ownership of this object to another user
- Parameters:
- idint
The ID of the resource that is shared.
- user_idint
ID of target user
- include_dependenciesbool
Whether or not to give manage permissions on all dependencies
- email_bodystr, optional
Custom body text for e-mail sent on transfer.
- send_emailbool, optional
Send email to the target user of the transfer?
- Returns:
civis.response.Response
- dependenciesList[dict]
Dependent objects for this object
- object_typestr
Dependent object type
- fco_typestr
Human readable dependent object type
- idint
Dependent object ID
- namestr
Dependent object name, or nil if the requesting user cannot read this object
- permission_levelstr
Permission level of target user (not user’s groups) for dependent object. Null if no target user or not shareable (e.g. a database table).
- descriptionstr
Additional information about the dependency, if relevant
- sharedbool
Whether dependent object was successfully shared with target user