Get job history (GET)

Description

URL

scheme://domain:port/platform/ws/jobhistory

Description

By default, displays historical information for jobs in the LSF states PEND, RUN, PSUSP, USUSP, SSUSP, submitted by the logged in user in the past week.

You can only get information about jobs submitted by the logged in user account. You must be an LSF administrator or LSF user group administrator to get information about jobs submitted by other users.

The time period to display can be changed by setting the environment variable LSB_BHIST_HOURS to an alternative number of hours.

Searches the event log file currently used by the LSF system: $LSB_SHAREDIR/cluster_name/logdir/lsb.events).

HTTP Method

GET

Parameters

Name Description
 

ids

Optional.

Gets historical information for jobs that have the specified job IDs.

To specify multiple job IDs, separate with a comma(,). For example: 532,533.

The job ID cannot be 0.

If a job ID is specified, all other parameters are ignored.

Note: Job arrays are not supported.
 

jobname

Optional.

Gets historical information about jobs that have the specified job name.

The job name can be up to 4094 characters long. Job names are not unique.

You can use the wildcard character (*) anywhere within a job name. For example, job* returns jobA, jobB, jobC, and so on.

 

username

Optional.

If user name is not specified, gets information about jobs submitted by the logged in user.

OS user name or LSF user group name. You must be an LSF administrator or group administrator to use this parameter.

Gets historical information about jobs submitted by the specified user, or jobs submitted by users belonging to the specified LSF user group.

Use the keyword all to return historical information for jobs submitted by all users.

To specify a windows user name, use the format DOMAIN_NAME\\user_name. For example: mydomain\\user1.

To get a list of users, use the API /platform/ws/users.

To get a list of user groups, use the API /platform/ws/usergroups.

 

queuename

Optional.

Gets historical information about jobs in the specified queue.

To get a list of queues, use the API /platform/ws/queues.

 

hostname

Optional.

Gets historical information about jobs that have been dispatched to the specified host or jobs that have been dispatched to all hosts in the specified host group.

To get a list of hosts, use the API /platform/ws/hosts.

To get a list of host groups, use the API /platform/ws/hostgroups.

 

status

Optional.

Gets historical information about jobs with the specified job status. To specify multiple states, separate with a comma (,). For example: status= PENDING,EXIT,SUSPENDED.

If status is not specified, gets historical information about jobs in the LSF states PEND, RUN, PSUSP, USUSP, SSUSP.

Valid values:

  • PENDING: Gets historical information about jobs that have the LSF status PEND.
  • SUSPENDED: Get historical information about jobs that have the LSF status PSUSP, USUSP, SSUSP.
  • RUNNING: Gets historical information about jobs that have the LSF status RUN.
  • DONE: Gets historical information about jobs that have the LSF status DONE.
  • EXIT: Gets historical information about jobs that have the LSF status EXIT.
 

start

Optional.  The start index for job paging. Must be a positive integer.

If this parameter is not set, the default start number is 1.

For example, if there are 1024 jobs to return from LSF, and you set start to 20 and pagesize to 50, the API returns 50 jobs, and the first job of these 50 jobs is the twentieth job of all 50 jobs:

/platform/jobhistory?start=20&pagesize=50

 

pagesize

Optional. Maximum number of jobs that are returned. Must be a positive integer.

If this parameter is not set, the default is to return all jobs.

Request

Request-Method

GET

Request-URI

/platform/ws/jobhistory?ids=%s

OR

/platform/ws/jobhistory?jobname=%s&username=%s&queuename=%s&hostname=%s&status=%s&start=%d&pagesize=%d

Request-Header

Name Value

Accept

application/xml or application/json

Message-body

empty

Response

Response-Code

  • 200 Successful: Request was successful.
  • 401 Unauthorized: Token is not valid.
  • 403 Forbidden: Access restricted by role-based access control permissions.
  • 404 Not Found: No jobs that match the specified criteria found.
  • 500 Internal Server Error: Exception occurred

Response-Header

Name Value

Content-Type

application/xml or application/json

Message-body

Success Message

If successful, returns historical information about jobs.

For additional information, refer to the schema file ./schemas/jobs/jobhistory.xsd.


<jobHistory total="%s">
    <history>
        <jobSummary>
          <id>%s</id>
          <jobname>%s</jobname>
          <user>%s</user>
          <project>%s</project>
          <command>%s</command>
        </jobSummary>
	   <content>
          %s
       </content>
       <timeSummary>
		  <timeOfCalculation> %s</timeOfCalculation>
		  <pend>%s</pend>
		  <psusp>%s</psusp>
		  <run>%s</run>
		  <ususp>%s</ususp>
		  <ssusp>%s</ssusp>
		  <unknown>%s</unknown>
       </timeSummary>
    </history>
    <history>
      <jobSummary>
          ...
        </jobSummary>
	   <content>
          ...
       </content>
       <timeSummary>
		  ...
       </timeSummary>
    </history>
</jobHistory>
Failure Message

If not successful, returns an error message.

For additional information, refer to the schema file ./schemas/jobs/error.xsd.

<error>
  <message>
     %s
  </message>
</error>

Related APIs

  • Get a list of users: /platform/ws/users
  • Get a list of user groups: /platform/ws/usergroups
  • Get a list of queues: /platform/ws/queues
  • Get a list of hosts: /platform/ws/hosts
  • Get a list of host groups: /platform/ws/hostgroups