!CHAPTER Managing Async Results via HTTP

`PUT /_api/job/job-id`*(Returns the result of an async job)*

!SUBSECTION URL parameters

`job-id (string,required)`

The async job id.

!SUBSECTION Description

Returns the result of an async job identified by job-id. If the async job result is present on the server, the result will be removed from the list of result. That means this method can be called for each job-id once.
The method will return the original job result's headers and body, plus the additional HTTP header x-arango-async-job-id. If this header is present, then the job was found and the response contains the original job's result. If the header is not present, the job was not found and the response contains status information from the job amanger.

!SUBSECTION Return codes

Any HTTP status code might be returned by this method. To tell the original job response from a job manager response apart, check for the HTTP header x-arango-async-id. If it is present, the response contains the original job's result. Otherwise the response is from the job manager.

`HTTP 204`

is returned if the job requested via job-id is still in the queue of pending (or not yet finished) jobs. In this case, no x-arango-async-id HTTP header will be returned.

`HTTP 400`

is returned if no job-id was specified in the request. In this case, no x-arango-async-id HTTP header will be returned.

`HTTP 404`

is returned if the job was not found or already deleted or fetched from the job result list. In this case, no x-arango-async-id HTTP header will be returned.

*Examples*

Not providing a job-id:

```
unix> curl -X PUT --dump - http://localhost:8529/_api/job/

HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8

{"error":true,"errorMessage":"bad parameter","code":400,"errorNum":400}
```

Providing a job-id for a non-existing job:

```
unix> curl -X PUT --dump - http://localhost:8529/_api/job/foobar

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8

{"error":true,"errorMessage":"not found","code":404,"errorNum":404}
```

Fetching the result of an HTTP GET job:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 265413601

unix> curl -X PUT --dump - http://localhost:8529/_api/job/265413601

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-arango-async-id: 265413601

{"server":"arango","version":"2.1.0"}
```

Fetching the result of an HTTP POST job that failed:

```
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/collection
{"name":" this name is invalid "}

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 265479137

unix> curl -X PUT --dump - http://localhost:8529/_api/job/265479137

HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
x-arango-async-id: 265479137

{"error":true,"code":400,"errorNum":1208,"errorMessage":"cannot create collection: illegal name"}
```

`PUT /_api/job/job-id/cancel`*(Cancels an async job)*

!SUBSECTION URL parameters

`job-id (string,required)`

The async job id.

!SUBSECTION Description

Cancels the currently running job identified by job-id. Note that it still might take some time to actually cancel the running async job.

!SUBSECTION Return codes

Any HTTP status code might be returned by this method. To tell the original job response from a job manager response apart, check for the HTTP header x-arango-async-id. If it is present, the response contains the original job's result. Otherwise the response is from the job manager.

`HTTP 200`

cancel has been initiated.

`HTTP 400`

is returned if no job-id was specified in the request. In this case, no x-arango-async-id HTTP header will be returned.

`HTTP 404`

is returned if the job was not found or already deleted or fetched from the job result list. In this case, no x-arango-async-id HTTP header will be returned.

*Examples*

```
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/cursor
{"query": "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"}

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 268952545

unix> curl --dump - http://localhost:8529/_api/job/pending

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

["268952545"]

unix> curl -X PUT --dump - http://localhost:8529/_api/job/268952545/cancel

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{"result":true}

unix> curl --dump - http://localhost:8529/_api/job/pending

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

["268952545"]
```

`DELETE /_api/job/type`*(Deletes the result of async jobs)*

!SUBSECTION URL parameters

`type (string,required)`

The type of jobs to delete. type can be:

* all: deletes all jobs results. Currently executing or queued async jobs will not be stopped by this call.
* expired: deletes expired results. To determine the expiration status of a result, pass the stamp URL parameter. stamp needs to be a UNIX timestamp, and all async job results created at a lower timestamp will be deleted.
* an actual job-id: in this case, the call will remove the result of the specified async job. If the job is currently executing or queued, it will not be aborted.

!SUBSECTION Query parameters

`stamp (number,optional)`

A UNIX timestamp specifying the expiration threshold when type is expired.

!SUBSECTION Description

Deletes either all job results, expired job results, or the result of a specific job. Clients can use this method to perform an eventual garbage collection of job results.

!SUBSECTION Return codes

`HTTP 200`

is returned if the deletion operation was carried out successfully. This code will also be returned if no results were deleted.

`HTTP 400`

is returned if type is not specified or has an invalid value.

`HTTP 404`

is returned if type is a job-id but no async job with the specified id was found.

*Examples*

Deleting all jobs:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270132193

unix> curl -X DELETE --dump - http://localhost:8529/_api/job/all

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{ 
  "result" : true 
}
```

Deleting expired jobs:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270197729

unix> curl -X DELETE --dump - http://localhost:8529/_api/job/expired?stamp=1401376184

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{ 
  "result" : true 
}
```

Deleting the result of a specific job:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270263265

unix> curl -X DELETE --dump - http://localhost:8529/_api/job/270263265

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{ 
  "result" : true 
}
```

Deleting the result of a non-existing job:

```
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/foobar

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8

{ 
  "error" : true, 
  "errorMessage" : "not found", 
  "code" : 404, 
  "errorNum" : 404 
}
```

`GET /_api/job/job-id`*(Returns the status of the specified job)*

!SUBSECTION URL parameters

`job-id (string,required)`

The async job id.

!SUBSECTION Description

Returns the processing status of the specified job. The processing status can be determined by peeking into the HTTP response code of the response.
!SUBSECTION Return codes

`HTTP 200`

is returned if the job requested via job-id has been executed successfully and its result is ready to fetch.

`HTTP 204`

is returned if the job requested via job-id is still in the queue of pending (or not yet finished) jobs.

`HTTP 400`

is returned if no job-id was specified in the request.

`HTTP 404`

is returned if the job was not found or already deleted or fetched from the job result list.

*Examples*

Querying the status of a done job:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270328801

unix> curl --dump - http://localhost:8529/_api/job/270328801

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8

Querying the status of a pending job:

unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_admin/sleep?duration=3

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270394337

unix> curl --dump - http://localhost:8529/_api/job/270394337

HTTP/1.1 204 No Content
content-type: text/plain; charset=utf-8
```

`GET /_api/job/type`*(Returns the list of job result ids with a specific status)*

!SUBSECTION URL parameters

`type (string,required)`

The type of jobs to return. The type can be either done or pending. Setting the type to done will make the method return the ids of already completed async jobs for which results can be fetched. Setting the type to pending will return the ids of not yet finished async jobs.

!SUBSECTION Query parameters

`count (number,optional)`

The maximum number of ids to return per call. If not specified, a server-defined maximum value will be used.

!SUBSECTION Description

Returns the list of ids of async jobs with a specific status (either done or pending). The list can be used by the client to get an overview of the job system status and to retrieve completed job results later.

!SUBSECTION Return codes

`HTTP 200`

is returned if the list can be compiled successfully. Note: the list might be empty.

`HTTP 400`

is returned if type is not specified or has an invalid value.

*Examples*

Fetching the list of done jobs:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270459873

unix> curl --dump - http://localhost:8529/_api/job/done

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[ 
  "270459873" 
]
```

Fetching the list of pending jobs:

```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version

HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270525409

unix> curl --dump - http://localhost:8529/_api/job/pending

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[ ]
```