Content Management API > Asynchronous jobs

For some endpoints whose tasks are potentially time-consuming (e.g., updating a Model), the API does not return a 200 OK status code. Instead, a 202 Accepted status code is returned, and an asynchronous job starts in the background, which will complete shortly.

The payload of a 202 Accepted response contains the ID of the asynchronous job that started:

1
PUT https://site-api.datocms.com/item-types/:model_id_or_api_key HTTP/1.1
2
X-Api-Version: 3
3
Authorization: Bearer YOUR-API-TOKEN
4
Accept: application/json
5
Content-Type: application/json
6

7
{ ... }
8

9
HTTP/1.1 202 Accepted
10
Content-Type: application/json
11

12
{
13
  "data": {
14
    "type": "job",
15
    "id": "4235"
16
  }
17
}

To get the result of of the asynchronous job, you need to poll the Job result endpoint. As long as the task is in progress, the endpoint will return a 404 Not found status code. As soon as the job completes, the status will change to 200 OK:

1
GET https://site-api.datocms.com/job-results/:job_result_id HTTP/1.1
2
X-Api-Version: 3
3
Authorization: Bearer YOUR-API-TOKEN
4
Accept: application/json
5

6
HTTP/1.1 200 OK
7
Content-Type: application/json
8

9
{
10
  "data": {
11
    "type": "job_result",
12
    "id": "34",
13
    "attributes": {
14
      "status": 200,
15
      "payload": {
16
        "data": { ... }
17
      }
18
    }
19
  }
20
}

In the payload of the response you'll find both the status code and the payload of the original request you performed.

Important: all endpoints could return async jobs in the future!

If you are using our Content Management API directly, without any of our official clients, you need to make sure to treat all endpoints as they might return an asynchronous job.

This is a fundamental constraint of using our Content Management API. In the event that an endpoint needs to be optimized, we want to leave ourselves the ability to return an asynchronous job without having to release a new API version.

If you are implementing a custom client yourself, the easiest way to proceed is to wrap every request you make to our API to a common logic that checks if the response is a job, and if so, it polls for its result before returning anything to the caller.