Jobs

class Jobs(session_kwargs, client, return_type='raw')

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.jobs.list(...)

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

post_trigger_email(id)

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

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

delete_shares_groups(id: int, group_id: int)

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

delete_shares_users(id: int, user_id: int)

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_shares(id: int)

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

put_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

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.

put_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

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