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 have the following attributes.

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned when the job is queued
url string yes no The URL to poll for status updates
total integer yes no The total number of tasks this job is batching through
progress integer yes no Number of tasks that have already been completed
status string yes no The current status. One of the following: "queued", "working", "failed", "completed", "killed"
message string yes no Message from the job worker, if any
results array yes no Result data from processed tasks. See Results below
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. 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)

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")
Examples

Bulk update

{
  "job_status": {
    "id": "82de0b044094f0c67893ac9fe64f1a99",
    "url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json",
    "total": 2,
    "progress": 2,
    "status": "completed",
    "message": "Completed at 2018-03-08 10:07:04 +0000",
    "results": [
      {
        "id": 244,
        "action": "update",
        "success": true,
        "status": "Updated"
      },
      {
        "id": 245,
        "action": "update",
        "success": true,
        "status": "Updated"
      }
    ]
  }
}

Bulk create

{
  "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
      }
    ]
  }
}

List Job Statuses

GET /api/v2/job_statuses.json

Shows the current statuses for background jobs running.

Allowed For:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/job_statuses.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "job_statuses": [
    {
      "id": "8b726e606741012ffc2d782bcb7848fe",
      "status": "completed",
      ...
    },
    {
     "id": "e7665094164c498781ebe4c8db6d2af5",
     "status": "completed",
     ...
    }
  ]
}

Show Job Status

GET /api/v2/job_statuses/{id}.json

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/job_statuses/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "job_status": {
    "id":       "8b726e606741012ffc2d782bcb7848fe",
    "url":      "https://company.zendesk.com/api/v2/job_statuses/8b726e606741012ffc2d782bcb7848fe.json",
    "total":    2,
    "progress": 2,
    "status":   "completed",
    "message":  "Completed at Fri Apr 13 02:51:53 +0000 2012",
    "results": [
      {
        "title":   "I accidentally the whole bottle",
        "action":  "update",
        "errors":  "",
        "id":      380,
        "success": true,
        "status":  "Updated"
      },
      ...
    ]
  }
}

Show Many Job Statuses

GET /api/v2/job_statuses/show_many.json?ids={ids}

Accepts a comma-separated list of job status ids.

Allowed For:
  • Agents
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/job_statuses/show_many.json?ids=8b726e606741012ffc2d782bcb7848fe,e7665094164c498781ebe4c8db6d2af5,3f3a876fb3354766b74a21066007ffee \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "job_statuses": [
    {
      "id": "8b726e606741012ffc2d782bcb7848fe",
      "status": "completed",
      ...
    },
    {
     "id": "e7665094164c498781ebe4c8db6d2af5",
     "status": "completed",
     ...
    }
  ]
}