Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account

Jobs device HTTP API

PDF
Focus mode
Jobs device HTTP API - AWS IoT Core

Devices can communicate with AWS IoT Jobs using HTTP Signature Version 4 on port 443. This is the method used by the AWS SDKs and CLI. For more information about those tools, see AWS CLI Command Reference:iot-jobs-data or AWS SDKs and Tools.

The following commands are available for devices executing the jobs. For information about using API operations with the MQTT protocol, see Jobs device MQTT API operations.

Gets the list of all jobs that aren't in a terminal state, for a specified thing.

HTTPS request
GET /things/thingName/jobs

Response:

{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ]
}

For more information, see GetPendingJobExecutions.

CLI syntax
aws iot-jobs-data get-pending-job-executions \
--thing-name <value>  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"thingName": "string"
}

For more information, see get-pending-job-executions.

Gets the list of all jobs that aren't in a terminal state, for a specified thing.

HTTPS request
GET /things/thingName/jobs

Response:

{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ]
}

For more information, see GetPendingJobExecutions.

CLI syntax
aws iot-jobs-data get-pending-job-executions \
--thing-name <value>  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"thingName": "string"
}

For more information, see get-pending-job-executions.

anchoranchor
GET /things/thingName/jobs

Response:

{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ]
}

For more information, see GetPendingJobExecutions.

Gets and starts the next pending job execution for a thing (with a status of IN_PROGRESS or QUEUED).

  • Any job executions with status IN_PROGRESS are returned first.

  • Job executions are returned in the order in which they were created.

  • If the next pending job execution is QUEUED, its status changes to IN_PROGRESS and the job execution's status details are set as specified.

  • If the next pending job execution is already IN_PROGRESS, its status details don't change.

  • If no job executions are pending, the response doesn't include the execution field.

  • Optionally, you can create a step timer by setting a value for the stepTimeoutInMinutes property. If you don't update the value of this property by running UpdateJobExecution, the job execution times out when the step timer expires.

HTTPS request

The following example shows the request syntax:

PUT /things/thingName/jobs/$next
{
"statusDetails": { 
    "string": "string" 
    ... 
},
"stepTimeoutInMinutes": long
}

For more information, see StartNextPendingJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  start-next-pending-job-execution \
--thing-name <value> \
{--step-timeout-in-minutes <value>] \
[--status-details <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}

For more information, see start-next-pending-job-execution.

Gets and starts the next pending job execution for a thing (with a status of IN_PROGRESS or QUEUED).

  • Any job executions with status IN_PROGRESS are returned first.

  • Job executions are returned in the order in which they were created.

  • If the next pending job execution is QUEUED, its status changes to IN_PROGRESS and the job execution's status details are set as specified.

  • If the next pending job execution is already IN_PROGRESS, its status details don't change.

  • If no job executions are pending, the response doesn't include the execution field.

  • Optionally, you can create a step timer by setting a value for the stepTimeoutInMinutes property. If you don't update the value of this property by running UpdateJobExecution, the job execution times out when the step timer expires.

HTTPS request

The following example shows the request syntax:

PUT /things/thingName/jobs/$next
{
"statusDetails": { 
    "string": "string" 
    ... 
},
"stepTimeoutInMinutes": long
}

For more information, see StartNextPendingJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  start-next-pending-job-execution \
--thing-name <value> \
{--step-timeout-in-minutes <value>] \
[--status-details <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}

For more information, see start-next-pending-job-execution.

anchoranchor

The following example shows the request syntax:

PUT /things/thingName/jobs/$next
{
"statusDetails": { 
    "string": "string" 
    ... 
},
"stepTimeoutInMinutes": long
}

For more information, see StartNextPendingJobExecution.

Gets detailed information about a job execution.

You can set the jobId to $next to return the next pending job execution for a thing. The job's execution status must be QUEUED or IN_PROGRESS.

HTTPS request

Request:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument

Response:

{
"execution" : JobExecution,
}

For more information, see DescribeJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  describe-job-execution \
--job-id <value> \
--thing-name <value> \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}

For more information, see describe-job-execution.

Gets detailed information about a job execution.

You can set the jobId to $next to return the next pending job execution for a thing. The job's execution status must be QUEUED or IN_PROGRESS.

HTTPS request

Request:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument

Response:

{
"execution" : JobExecution,
}

For more information, see DescribeJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  describe-job-execution \
--job-id <value> \
--thing-name <value> \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}

For more information, see describe-job-execution.

anchoranchor

Request:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument

Response:

{
"execution" : JobExecution,
}

For more information, see DescribeJobExecution.

Updates the status of a job execution. Optionally, you can create a step timer by setting a value for the stepTimeoutInMinutes property. If you don't update the value of this property by running UpdateJobExecution again, the job execution times out when the step timer expires.

HTTPS request

Request:

POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long 
}

For more information, see UpdateJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  update-job-execution \
--job-id <value> \
--thing-name <value> \
--status <value> \
[--status-details <value>] \
[--expected-version <value>] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--step-timeout-in-minutes <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}

For more information, see update-job-execution.

Updates the status of a job execution. Optionally, you can create a step timer by setting a value for the stepTimeoutInMinutes property. If you don't update the value of this property by running UpdateJobExecution again, the job execution times out when the step timer expires.

HTTPS request

Request:

POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long 
}

For more information, see UpdateJobExecution.

CLI syntax

Synopsis:

aws iot-jobs-data  update-job-execution \
--job-id <value> \
--thing-name <value> \
--status <value> \
[--status-details <value>] \
[--expected-version <value>] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--step-timeout-in-minutes <value>] \
[--generate-cli-skeleton]

cli-input-json format:

{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}

For more information, see update-job-execution.

anchoranchor

Request:

POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long 
}

For more information, see UpdateJobExecution.

Related resources

AWS IoT Core API Reference
AWS CLI commands for AWS IoT Core
SDKs & Tools 

Related resources

AWS IoT Core API Reference
AWS CLI commands for AWS IoT Core
SDKs & Tools 
PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.