HTTP interface for jobs
The HTTP API for jobs lets you access the results of asynchronously executed requests and check the status of such jobs
Get the results of an async job
put
/_api/job/{job-id}
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 manager.
Responses
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.
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.
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:
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job
Show outputHTTP/1.1 400 Bad Request
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 71
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"code" : 400,
"error" : true,
"errorMessage" : "bad parameter",
"errorNum" : 400
}
Providing a job-id for a non-existing job:
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere
Show outputHTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 67
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"code" : 404,
"error" : true,
"errorMessage" : "not found",
"errorNum" : 404
}
Fetching the result of an HTTP GET job:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/67821
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 67821
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 79
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 67821
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"server" : "arango",
"license" : "enterprise",
"version" : "3.10.11-nightly.20230918"
}
Fetching the result of an HTTP POST job that failed:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
"name": " this name is invalid "
}
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/67849
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 67849
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 400 Bad Request
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 114
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 67849
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"code" : 400,
"error" : true,
"errorMessage" : "expected PUT /_api/collection/<collection-name>/<action>",
"errorNum" : 400
}
Cancel an async job
put
/_api/job/{job-id}/cancel
Cancels the currently running job identified by job-id. Note that it still
might take some time to actually cancel the running async job.
Responses
200
cancel has been initiated.
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.
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
curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --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"
}
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/67886/cancel
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 67886
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 9
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[
"67886"
]
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 15
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"result" : true
}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 9
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[
"67886"
]
Delete async job results
delete
/_api/job/{job-id}
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.
Path Parameters
job-id* string
The ID of the job to delete. The ID can be
all Deletes all jobs results. Currently executing or queued async
jobs are not stopped by this call.expired Deletes expired results. To determine the expiration status of a
result, pass the stamp query parameter. stamp needs to be a Unix timestamp,
and all async job results created before this time are deleted.- A numeric job ID In this case, the call removes the result of the
specified async job. If the job is currently executing or queued, it is
not aborted.
Query Parameters
stamp number
A Unix timestamp specifying the expiration threshold for when the job-id is
set to expired.
Responses
200
is returned if the deletion operation was carried out successfully.
This code will also be returned if no results were deleted.
400
is returned if job-id is not specified or has an invalid value.
404
is returned if job-id is a syntactically valid job ID but no async job with
the specified ID is found.
Examples
Deleting all jobs:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68058
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 15
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"result" : true
}
Deleting expired jobs:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1695137865.496756
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68235
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 51
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"time" : 1695137865.496756
}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 15
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"result" : true
}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 2
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[ ]
Deleting the result of a specific job:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/68417
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68417
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 15
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"result" : true
}
Deleting the result of a non-existing job:
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere
Show outputHTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 67
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"code" : 404,
"error" : true,
"errorMessage" : "not found",
"errorNum" : 404
}
List async jobs by status or get the status of specific job
get
/_api/job/{job-id}
This endpoint returns either of the following, depending on the specified value
for the job-id parameter:
- The IDs of async jobs with a specific status
- The processing status of a specific async job
Path Parameters
job-id* string
If you provide a value of pending or done, then the endpoint returns an
array of strings with the job IDs of ongoing or completed async jobs.
If you provide a numeric job ID, then the endpoint returns the status of the
specific async job in the form of an HTTP reply without payload. Check the
HTTP status code of the response for the job status.
Query Parameters
count number
The maximum number of job IDs to return per call. If not specified, a
server-defined maximum value is used. Only applicable if you specify pending
or done as job-id to list jobs.
Responses
200
is returned if the job with the specified job-id has finished and you can
fetch its results, or if your request for the list of pending or done jobs
is successful (the list might be empty).
204
is returned if the job with the specified job-id is still in the queue of
pending (or not yet finished) jobs.
400
is returned if you specified an invalid value for job-id or no value.
404
is returned if the job cannot be found or is already fetched or deleted from the
job result list.
Examples
Querying the status of a done job:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/68639
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68639
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Querying the status of a pending job:
(therefore we create a long running job…)
curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction
{
"collections": {
"read": [
"_aqlfunctions"
]
},
"action": "function () {require('internal').sleep(15.0);}"
}
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/68695
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68695
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 204 No Content
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Fetching the list of done jobs:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68897
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 17
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[
"68897",
"68639"
]
Fetching the list of pending jobs:
curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 68984
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 9
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[
"68695"
]
Fetching the list of a pending jobs while a long-running job is executing
(and aborting it):
curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction
{
"collections": {
"read": [
"_frontend"
]
},
"action": "function () {require('internal').sleep(15.0);}"
}
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/69073
Show outputHTTP/1.1 202 Accepted
content-type: text/plain
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-async-id: 69073
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 17
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
[
"69073",
"68695"
]
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 15
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"result" : true
}
