ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.
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
For an introduction to non-blocking execution of requests and how to create
async jobs with the x-arango-async
request header, see
HTTP request handling in ArangoDB.
Get the results of an async job
Returns the result of an async job identified by job-id
if it’s ready.
If the async job result is available on the server, the endpoint returns
the original operation’s result headers and body, plus the additional
x-arango-async-job-id
HTTP header. The result and job are then removed
which means that you can retrieve the result exactly once.
If the result is not available yet or if the job is not known (anymore), the additional header is not present and you can tell the status from the HTTP status code.
default (Varying HTTP status codes)
If the job has finished, you get the result with the headers of the original operation with an additional
x-arango-async-id
HTTP header. The HTTP status code is also that of the operation that executed asynchronously, which can be a success or error code depending on the outcome of the operation.
Examples
Not providing a job-id
:
curl -X PUT --header 'accept: application/json' --dump - 'http://localhost:8529/_api/job'
Show output
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: 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 output
HTTP/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/68892'
Show output
HTTP/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: 68892
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: 78
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: 68892
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"server" : "arango",
"license" : "enterprise",
"version" : "3.12.1-nightly.20240521"
}
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' <<'EOF'
{
"name": " this name is invalid "
}
EOF
curl -X PUT --header 'accept: application/json' --dump - 'http://localhost:8529/_api/job/68919'
Show output
HTTP/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: 68919
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: 68919
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
job-id
. Note that it still
might take some time to actually cancel the running async job.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/68666/cancel
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
Show output
HTTP/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: 68666
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
[
"68666"
]
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
[
"68666"
]
Delete async job results
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.
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 output
HTTP/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: 68704
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=1710183856.9466808
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
Show output
HTTP/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: 68773
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: 55
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" : 1710183856.9466808
}
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/68840
Show output
HTTP/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: 68840
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 output
HTTP/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
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
job-id* string
If you provide a value of
pending
ordone
, 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.
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/69147
Show output
HTTP/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: 69147
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/69249
Show output
HTTP/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: 69249
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 output
HTTP/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: 69367
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
[
"69367",
"69147"
]
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 output
HTTP/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: 69488
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
[
"69249"
]
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/69615
Show output
HTTP/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: 69615
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
[
"69249",
"69615"
]
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
}