Use ListJobs to query batch jobs - Object Storage Service

You can call the ListJobs operation to query batch jobs.

Permissions

By default, an Alibaba Cloud account has all permissions. However, a Resource Access Management (RAM) user or a RAM role does not have any permissions. The Alibaba Cloud account or an administrator must grant permissions to the RAM user or RAM role using a RAM policy or a bucket policy.

API	Action	Description
ListJobs	`oss:ListJobs`	Queries batch operation jobs.

Request syntax

GET /?batchJob&batchJobStatuses=JobStatuses&max-keys=MaxKeys&continuation-token=ContinuationToken HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

Request parameters

Name	Type	Required	Example	Description
batchJobStatuses	String	No	Complete	The filter condition for job status. This parameter filters the query results. If you do not set this parameter, jobs in all states are returned by default. Valid values: Active, Cancelled, Cancelling, Complete, Completing, Failed, Failing, New, Paused, Pausing, Preparing, Ready, and Suspended. You can specify multiple values, such as Active \| Cancelled \| Cancelling. Parent node: None
max-keys	Integer	No	100	The maximum number of jobs to return in a paged query. The value must be an integer from 1 to 1,000. The default value is 100. Parent node: None
continuation-token	String	No	next-page-token-123	The pagination token for a paged query. If a query does not return all results, the server returns NextToken. Use this token as the continuation-token for the next query to retrieve the remaining results. The token can be 1 to 1,024 characters in length and can contain uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and the following special characters: +, :, /, =, ?, #, -, and _. Parent node: None

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Response elements

Name	Type	Example	Description
ListJobsResult	Container	None	The root node of the response. Parent node: None Child nodes: NextToken and Jobs
NextToken	String	next-page-token-456	The token for the next page. If a query does not return all results, this element is included in the response. You can use this token as the continuation-token for the next query to retrieve the remaining results. Parent node: ListJobsResult
Jobs	Container	None	The container for the list of jobs. Parent node: ListJobsResult Child node: JobListDescriptor
JobListDescriptor	Container	None	The description of the job. Parent node: Jobs Child nodes: CreationTime, Description, JobId, Operation, Priority, ProgressSummary, Status, and TerminationDate
CreationTime	Timestamp	1749983400	The time when the job was created. Parent node: JobListDescriptor
Description	String	Batch job for setting object tags	The description of the job. Parent node: JobListDescriptor
JobId	String	MzRjZGU2NGQ3YTY5NGRhMTkxZmZhYzY5OTM5YTcxYWU=	The job ID. Parent node: JobListDescriptor
Operation	String	PutObjectTagging	The operation that the job performs. Parent node: JobListDescriptor
Priority	Integer	10	The priority of the job. Parent node: JobListDescriptor
ProgressSummary	Container	None	The summary of the current job progress. Parent node: JobListDescriptor Child nodes: NumberOfTasksFailed, NumberOfTasksSucceeded, Timers, and TotalNumberOfTasks
NumberOfTasksFailed	Long	0	The number of failed tasks. Parent node: ProgressSummary
NumberOfTasksSucceeded	Long	1000	The number of successful tasks. Parent node: ProgressSummary
Timers	Container	None	The information about the running time. Parent node: ProgressSummary Child node: ElapsedTimeInActiveSeconds
ElapsedTimeInActiveSeconds	Long	3600	The running time in seconds. Parent node: Timers
TotalNumberOfTasks	Long	1000	The total number of tasks. Parent node: ProgressSummary
Status	String	Complete	The current running state. Valid values: New: The job is newly created and has not started preparations. Preparing: The system is parsing the manifest file, authenticating permissions, and initializing resources. Ready: The job has completed preparations and is waiting to be scheduled and executed by the system. Suspended: The job requires explicit confirmation from the user to continue. This happens when ConfirmationRequired is set to true during job creation. Active: The job is processing objects in batches. You can view the real-time progress in ProgressSummary. Pausing: The system is pausing the job. This applies only to this job. Paused: The job is paused. The OSS service automatically resumes the job. Completing: All objects have been processed. The system is generating an execution report and cleaning up resources. Complete: The job is successfully completed. This is a desired state. Cancelling: The system is canceling the job. Cancelled: The job was canceled by the user. This is a desired state. Failing: The job encountered a critical error, and the system is stopping its execution. Failed: The job was stopped due to a system-level error. For more information about the cause, see the FailureReasons field. This is a desired state. Parent node: JobListDescriptor
TerminationDate	Timestamp	1749987000	The time when the job was stopped. Parent node: JobListDescriptor

Response headers

This operation uses only common response headers. For more information, see Common response headers.

Examples

Request example

GET /?batchJob&batchJobStatuses=Complete&max-keys=10&continuation-token=next-page-token-123 HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

Response example

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<ListJobsResult>
   <NextToken>next-page-token-456</NextToken>
   <Jobs>
      <JobListDescriptor>
         <CreationTime>1749983400</CreationTime>
         <Description>Batch job for setting object tags</Description>
         <JobId>MzRjZGU2NGQ3YTY5NGRhMTkxZmZhYzY5OTM5YTcxYWU=</JobId>
         <Operation>PutObjectTagging</Operation>
         <Priority>10</Priority>
         <ProgressSummary>
            <NumberOfTasksFailed>0</NumberOfTasksFailed>
            <NumberOfTasksSucceeded>1000</NumberOfTasksSucceeded>
            <Timers>
               <ElapsedTimeInActiveSeconds>3600</ElapsedTimeInActiveSeconds>
            </Timers>
            <TotalNumberOfTasks>1000</TotalNumberOfTasks>
         </ProgressSummary>
         <Status>Complete</Status>
         <TerminationDate>1749987000</TerminationDate>
      </JobListDescriptor>
   </Jobs>
</ListJobsResult>