Menu
AWS IoT
Developer Guide

DescribeJob

Describes a job.

Request syntax:

GET /jobs/jobId

URI Request Parameters:

Name

Type

Req?

Description

jobId

JobId

yes

The unique identifier you assigned to this job when it was created.

Response syntax:

Content-type: application/json { "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } } }

Response Body Parameters:

Name

Type

Req?

Description

documentSource

JobDocumentSource

no

An S3 link to the job document.

job

Job

no

Information about the job.

Errors:

InvalidRequestException

The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.

HTTP response code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP response code: 404

ThrottlingException

The rate exceeds the limit.

HTTP response code: 429

ServiceUnavailableException

The service is temporarily unavailable.

HTTP response code: 503

CLI

Synopsis:

aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

Output:

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } } }

cli output fields:

Name

Type

Description

documentSource

string

length max:1350 min:1

An S3 link to the job document.

job

Job

Information about the job.

jobArn

string

An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".

jobId

string

length max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

targetSelection

string

enum: CONTINUOUS | SNAPSHOT

java class: com.amazonaws.iot.laser.TargetSelection

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a device when the thing representing the device is added to a target group, even after the job was completed by all things originally in the group.

status

string

enum: IN_PROGRESS | CANCELED | COMPLETED

java class: ccom.amazonaws.iot.laser.common.JobStatus

The status of the job, one of IN_PROGRESS, CANCELED, or COMPLETED.

comment

string

length max:2028

pattern: [^\\p{C}]+

If the job was updated, describes the reason for the update.

targets

list

member: TargetArn

A list of IoT things and thing groups to which the job should be sent.

TargetArn

string

description

string

length max:2028

pattern: [^\\p{C}]+

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

Configuration for pre-signed S3 URLs.

roleArn

string

length max:2048 min:20

The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.

expiresInSec

long

java class: java.lang.Long

range- max:3600 min:60

How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

Allows you to create a staged rollout of a job.

maximumPerMinute

integer

java class: java.lang.Integer

range- max:1000 min:1

The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.

createdAt

timestamp

The time, in milliseconds since the epoch, when the job was created.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job was last updated.

completedAt

timestamp

The time, in milliseconds since the epoch, when the job was completed.

jobProcessDetails

JobProcessDetails

Details about the job process.

processingTargets

list

member: ProcessingTargetName

java class: java.util.List

The devices on which the job is executing.

ProcessingTargetName

string

numberOfCanceledThings

integer

java class: java.lang.Integer

The number of things that cancelled the job.

numberOfSucceededThings

integer

java class: java.lang.Integer

The number of things which successfully completed the job.

numberOfFailedThings

integer

java class: java.lang.Integer

The number of things that failed executing the job.

numberOfRejectedThings

integer

java class: java.lang.Integer

The number of things that rejected the job.

numberOfQueuedThings

integer

java class: java.lang.Integer

The number of things that are awaiting execution of the job.

numberOfInProgressThings

integer

java class: java.lang.Integer

The number of things currently executing the job.

numberOfRemovedThings

integer

java class: java.lang.Integer

The number of things that are no longer scheduled to execute the job because they have been deleted or have been removed from the group that was a target of the job.

documentParameters

map

key: ParameterKey

value: ParameterValue

The parameters specified for the job document.

ParameterKey

string

length max:128 min:1

pattern: [a-zA-Z0-9:_-]+

ParameterValue

string

length max:1024 min:1

pattern: [^\\p{C}]+

On this page: