client.jobs.list

A method of the Jobs endpoint.

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) → ListResponse | PaginatedResponse

List Jobs

API URL: GET /jobs

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

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 items to return. One of: true, false, all. A blank value is read as ‘false’, which is also the default.

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, last_run_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 (specifically, a civis.PaginatedResponse object) to iterate over all responses. Use it when more results than the maximum allowed by ‘limit’ are needed. When True, ‘page_num’ is ignored. If False, return a civis.ListResponse object (= a list of civis.Response objects), whose size is determined by ‘limit’. Defaults to False.

Returns:

civis.ListResponse | civis.PaginatedResponse

• id : int

• name : str

• type : str

• from_template_id : int

• statestr

  Whether the job is queued, running, succeeded, failed, cancelled, idle or scheduled.

• created_at : str (date-time)

• updated_at : str (date-time)

• last_run_updated_at : str (date-time)

• last_runcivis.Response

  • id : int

  • statestr

    The state of the run. One of queued, running, succeeded, failed or cancelled.

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

• archivedbool

  The archival status of the requested item(s).

• authorcivis.Response

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

• schedulecivis.Response

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