Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

ListJobs

Lists current jobs and jobs that have ended within the last 30 days for the AWS account that is making the request. The job list that is returned is sorted by creation date, with the newest job first.

Request Syntax

GET /v20180820/jobs?jobStatuses=JobStatuses&maxResults=MaxResults&nextToken=NextToken HTTP/1.1 x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

jobStatuses

The List Jobs request returns jobs that match the statuses listed in this element. If you don't provide jobStatuses, the API returns all jobs. You can specify one or more jobStatuses as follows:

https://acct-id.s3-control.us-west-2.amazonaws.com/v20180820/jobs?jobStatuses=Active&jobStatuses=Complete&maxResults=2

Valid values: Active | Cancelled | Cancelling | Complete | Completing | Failed | Failing | New | Paused | Pausing | Preparing | Ready | Suspended

maxResults

The maximum number of jobs that Amazon S3 includes in the List Jobs response. If the number of jobs is higher than this number, the response includes a pagination token in the NextToken field to enable you to retrieve the next page of results. The operation might return fewer results than maxResults, but as long as the nextToken returned is not empty, there are more results that you can fetch.

Valid range: Minimum value of 1. Maximum value of 1000.

nextToken

A pagination token to request the next page of results. Use the token that Amazon S3 returned in the NextToken element of the ListJobsResult from the previous List Jobs request.

Length constraints: Minimum length of 1. Maximum length of 1024.

x-amz-account-id

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200 <?xml version="1.0" encoding="UTF-8"?> <ListJobsResult> <Jobs> <JobListDescriptor> <CreationTime>timestamp</CreationTime> <Description>string</Description> <JobId>string</JobId> <Operation>string</Operation> <Priority>integer</Priority> <ProgressSummary> <NumberOfTasksFailed>long</NumberOfTasksFailed> <NumberOfTasksSucceeded>long</NumberOfTasksSucceeded> <TotalNumberOfTasks>long</TotalNumberOfTasks> </ProgressSummary> <Status>string</Status> <TerminationDate>timestamp</TerminationDate> </JobListDescriptor> </Jobs> <NextToken>string</NextToken> </ListJobsResult>

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListJobsResult

A root-level tag for the ListJobsResult parameters.

Required: Yes

Jobs

The list of current jobs and jobs that have ended within the last 30 days. This is the list of jobs that match the job statuses specified in the request, if any.

Type: Array of JobListDescriptor objects

NextToken

If the List Jobs request produced more than the maximum number of results, you can pass this value into a subsequent List Jobs request to retrieve the next page of results. As long as the NextToken is not empty, there are more results you can fetch (regardless of the number of jobs that the operation produces in comparison to maxResults specified in the request).

Type: String

Length constraints: Minimum length of 1. Maximum length of 1024.

Errors

InternalServiceException

HTTP Status Code: 500

InvalidNextTokenException

HTTP Status Code: 400

InvalidRequestException

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: