Developer Guide

Managing Jobs

Jobs are created and managed using the Jobs HTTPS API, the AWS Command Line Interface or the AWS SDKs. For more information on these tools, see Job Management and Control API, AWS CLI Command Reference: iot or AWS SDKs and Tools.

Create Jobs

CreateJobmore info (1)granting permissions

You use the CreateJob command to create a job. The job is queued for execution on the targets (things or thing groups) that you specify. To create a job, you need a job document that can be included in the body of the request or as a link to an Amazon S3 document. If the job includes downloading files using presigned Amazon S3 URLs, you need an IAM role ARN that has permission to download the file and grants permission to AWS IoT to assume the role.

more info (1)

If you have a file called job-document.json stored in an Amazon S3 bucket called jobBucket and the role with permission to download files from Amazon S3 is called S3DownloadRole, the CLI command to create a job would look like this:

aws iot create-job \ --job-id 010 \ --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \ --document-source \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

If you want to specify the job document inline, use the --document parameter instead of the --document-source parameter.

A job is sent to and executed on targets in the order they appear in the --targets list. For example, if the targets list is:

[ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ]

then the job will be executed on thingOne, followed by the things in thinggroupOne then thingTwo and finally by the things in thinggroupTwo.


Job documents that are specified as Amazon S3 files are retrieved at the time you create the job. Changing the contents of the Amazon S3 file you used as the source of your job document after you have created the job does not change what is sent to the targets of the job.

granting permissions

When creating a job that uses presigned Amazon S3 URLs, you must provide an IAM role ARN that grants permission to download files from the Amazon S3 bucket where the data or updates are stored. The role must also grant permission for AWS IoT to assume the role.

To grant Jobs permission to assume your role:

  1. Sign in to the AWS Management Console and open the IAM console at

  2. In the left navigation pane, choose Roles.

  3. Search for your role and choose it.

  4. Choose the Trust Relationships tab.

  5. Choose the Edit Trust Relationship button.

  6. On the Edit Trust Relationship page, replace the policy document with the following JSON:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "" ] }, "Action": "sts:AssumeRole" } ] }
  7. Choose Update Trust Policy

You can optionally specify a timeout for the presigned URL. For more information, see CreateJob.

Cancel a Job

CancelJobmore info (2)

You use the the CancelJob command to cancel a job. Cancelling a job will stop AWS IoT rolling out any new job executions for the job. It will also cancel any job executions that have already been QUEUED. IoT will leave any job executions in an IN_PROGRESS or terminal status untouched because the device is already executing the job or has already completed it.

more info (2)
aws iot cancel-job --job-id 010

The command displays no output.

Job executions that are QUEUED will be canceled. Job executions that are IN_PROGRESS or in a terminal state are not canceled. The status of a canceled job or of one of its job execution is eventually consistent — IoT will stop scheduling new job executions and not present QUEUED job executions for that job to devices as soon as possible. But changing the status of a job execution to CANCELED may take some time depending on the number of devices and other factors.

Get a Job Document

GetJobDocumentmore info (3)

You use the GetJobDocument command to retrieve a job document for a job.

more info (3)
aws iot get-job-document --job-id 010

The command returns the job document for the specified job:

{ "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"\",\n\t\"data\":\"${aws:iot:s3-presigned-url:}\"\n}" }


When you retrieve a job document using this command, any placeholder URLs are not replaced by presigned Amazon S3 URLs. The placeholder URLs are replaced by presigned Amazon S3 URLs in the job document that is returned when a device calls the GetPendingJobExecutions MQTT API.

List Jobs

ListJobsmore info (4)

You use the ListJobs command to get a list of all jobs in your AWS account. Note that job data and job execution data will be purged after 90 days.

more info (4)
aws iot list-jobs

The command lists all jobs in your account sorted by the job status:

{ "jobs": [ { "status": "IN_PROGRESS", "lastUpdatedAt": 1486687079.743, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", "createdAt": 1486687079.743, "targetSelection": "SNAPSHOT", "jobId": "013" }, { "status": "COMPLETED", "lastUpdatedAt": 1486685868.444, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", "createdAt": 1486685868.444, "completedAt": 148668789.690, "targetSelection": "SNAPSHOT", "jobId": "012" }, { "status": "CANCELED", "lastUpdatedAt": 1486678850.575, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", "createdAt": 1486678850.575, "targetSelection": "SNAPSHOT", "jobId": "011" } ] }

Describe a Job

DescribeJobmore info (5)

You use the DescribeJob command to get the status of a specific job.

more info (5)
$ aws iot describe-job --job-id 010

The command returns the status of the specified job:

{ "documentSource": "", "job": { "status": "IN_PROGRESS", "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/myThing" ], "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfFailedThings": 0, "numberOfInProgressThings": 0, "numberOfQueuedThings": 0, "numberOfRejectedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 0, "processingTargets": [ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ] }, "presignedUrlConfig": { "expiresInSec": 60, "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole" }, "jobId": "010", "lastUpdatedAt": 1486593195.006, "createdAt": 1486593195.006, "targetSelection": "SNAPSHOT" } }

List Executions for a Job

ListJobExecutionsForJobmore info (6)

A job running on a specific device is represented by a job execution object. You use the ListJobExecutionsForJob command to list all job executions for a job.

more info (6)
aws iot list-job-executions-for-job --job-id 010

The command returns a list of job executions:

{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 1234567890 } }, { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1486593345.659, "queuedAt": 1486593196.378, "startedAt": 1486593345.659, "executionNumber": 4567890123 } } ] }

List Job Executions for a Thing

ListJobExecutionsForThingmore info (7)

You use the ListJobExecutionsForThing command to list all job executions running on a thing.

more info (7)
aws iot list-job-executions-for-thing --thing-name thingOne

The command returns a list of job executions that are running or have run on the specified thing:

{ "executionSummaries": [ { "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486687082.071, "queuedAt": 1486687082.071, "executionNumber": 9876543210 }, "jobId": "013" }, { "jobExecutionSummary": { "status": "IN_PROCESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "COMPLETED", "startAt": 1486678853.415, "lastUpdatedAt": 1486678853.415, "queuedAt": 1486678853.415, "executionNumber": 4357680912 }, "jobId": "011" }, { "jobExecutionSummary": { "status": "CANCELED", "startAt": 1486593196.378, "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 2143174250 }, "jobId": "010" } ] }

Describe Job Execution

DescribeJobExecutionmore info (8)

You use the DescribeJobExecution command to get the status of a specific job execution. You specify a job ID and thing name (and, optionally, an execution number) to identify the job execution.

The job's execution status must be QUEUED or IN_PROGRESS.

more info (8)
aws iot describe-job-execution --job-id 017 --thing-name thingOne

The command returns the JobExecution:

{ "execution": { "jobId": "017", "executionNumber": 4516820379, "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }

Jobs Events

Jobs also publishes to reserved topics on the MQTT protocol when jobs are pending, completed, or canceled, and when a device reports success or failure when executing a job. Devices or management and monitoring applications can keep track of the status of jobs by subscribing to these topics.

For more information about publishing and subscribing to MQTT topics, see Message Broker for AWS IoT

job pendingmore info (9)
job pending

AWS IoT Jobs publishes a message on an MQTT topic when a job is added to or removed from the list of pending job executions for a thing, or there is a change to the order to the jobs on the list:

  • $aws/things/thingName/jobs/notify

  • $aws/things/thingName/jobs/notify-next

more info (9)

The messages contain the following example payloads:


{ "jobs" : { "JobExecutionState": [ JobExecutionSummary ... ], }, "timestamp": timestamp, }


{ "execution" : JobExecutionData, "timestamp": timestamp, }
job completed/canceledmore info (10)
job completed/canceled

AWS IoT Jobs publishes a message on an MQTT topic when a job is completed or canceled:

  • $aws/events/job/jobID/completed

  • $aws/events/job/jobID/canceled

more info (10)

The "completed" message contains the following example payload:

{ "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } }

The "canceled" message contains the following example payload:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123 }
job execution terminal statusmore info (11)
job execution terminal status

AWS IoT Jobs publishes a message when a device updates a job execution to terminal status:

  • $aws/events/jobExecution/jobID/succeeded

  • $aws/events/jobExecution/jobID/failed

  • $aws/events/jobExecution/jobID/rejected

  • $aws/events/jobExecution/jobID/canceled

  • $aws/events/jobExecution/jobID/removed

Or, you can subscribe to all of these with:

  • $aws/events/jobExecution/jobID/#

more info (11)

The message contains the following example payload:

{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED", "statusDetails": { "key": "value" } }