Job Statuses
A status record is created when somebody kicks off a job such as updating multiple tickets. You can access the job status data for an hour after a particular job is created, after which the data is no longer available.
JSON format
Job Statuses are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
id | string | true | false | Automatically assigned when the job is queued |
message | string | true | false | Message from the job worker, if any |
progress | integer | true | false | Number of tasks that have already been completed |
results | true | false | Result data from processed tasks. See Results below | |
status | string | true | false | The current status. One of the following: "queued", "working", "failed", "completed", "killed" |
total | integer | true | false | The total number of tasks this job is batching through |
url | string | true | false | The URL to poll for status updates |
Results
The "results" array in a response lists the resources that were successfully and unsuccessfully updated or created after processing.
The results differ depending on the type of job.
Permanent Ticket Deletion
If the job was to permanently delete tickets, the result is an object that will only specify whether all of the tickets were successfully deleted or not ("success": true
).
{
"job_status": {
"id": "dd9321f29967688b27bc9499ebb4ae8d",
"url": "https://example.zendesk.com/api/v2/job_statuses/dd9321f299676c9499ebb4ae8d.json",
"total": null,
"progress": null,
"status": "completed",
"message": "Completed at 2018-03-08 06:07:49 +0000",
"results": {
"success": true
}
}
}
Bulk create
If the job was to bulk create resources, each result specifies the following:
- the id of the new resource (
"id": 245
) - the index number of the result (
"index": 1
)
Example
{
"job_status": {
"id": "dd9321f29967688b27bc9499ebb4ae8d",
"url": "https://example.zendesk.com/api/v2/job_statuses/dd9321f299676c9499ebb4ae8d.json",
"total": 2,
"progress": 2,
"status": "completed",
"message": "Completed at 2018-03-08 06:07:49 +0000",
"results": [
{
"id": 244,
"index": 0
},
{
"id": 245,
"index": 1
}
]
}
}
Bulk update
If the job was to bulk update resources, each result specifies the following:
- the id of the resource the job attempted to update (
"id": 255
) - the action the job attempted (
"action": "update"
) - whether the action was successful or not (
"success": true
) - the status (
"status": "Updated"
)
Example
{
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
List Job Statuses
GET /api/v2/job_statuses
Shows the current statuses for background jobs running.
Allowed For:
- Agents
cURL
curl https://{subdomain}.zendesk.com/api/v2/job_statuses.json \
-v -u {email_address}:{password}
Example response(s)
200 OK
// Status 200 OK
{
"job_statuses": [
{
"id": "8b726e606741012ffc2d782bcb7848fe",
"status": "completed"
},
{
"id": "e7665094164c498781ebe4c8db6d2af5",
"status": "completed"
}
]
}
Show Many Job Statuses
GET /api/v2/job_statuses/show_many?ids={ids}
Accepts a comma-separated list of job status ids.
Allowed For:
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of job status ids. |
cURL
curl https://{subdomain}.zendesk.com/api/v2/job_statuses/show_many.json?ids=8b726e606741012ffc2d782bcb7848fe,8b726e606741012ffc2d782bcb7848fe,e7665094164c498781ebe4c8db6d2af5 \
-v -u {email_address}:{password}
Example response(s)
200 OK
// Status 200 OK
{
"job_statuses": [
{
"id": "8b726e606741012ffc2d782bcb7848fe",
"status": "completed"
},
{
"id": "e7665094164c498781ebe4c8db6d2af5",
"status": "completed"
}
]
}
Show Job Status
GET /api/v2/job_statuses/{job_status_id}
Shows the status of a background job.
A job may no longer exist to query. Zendesk only logs the last 100 jobs. Jobs also expire within an hour.
Allowed For:
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
job_status_id | string | Path | true | the Id of the Job status |
cURL
curl https://{subdomain}.zendesk.com/api/v2/job_statuses/{job_status_id}.json \
-v -u {email_address}:{password}
Example response(s)
200 OK
// Status 200 OK
{
"job_status": {
"id": "8b726e606741012ffc2d782bcb7848fe",
"message": "Completed at Fri Apr 13 02:51:53 +0000 2012",
"progress": 2,
"results": [
{
"action": "update",
"id": 380,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://company.zendesk.com/api/v2/job_statuses/8b726e606741012ffc2d782bcb7848fe.json"
}
}