ArangoDB v3.10 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent stable version.

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.

Path Parameters

job-id* string
The async job id.

Query Parameters

HTTP Headers

Responses

204 No Content
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 Bad Request
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 Not Found
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 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/68114'

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: 68114
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: 62
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: 68114
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "server" : "arango", 
  "license" : "enterprise", 
  "version" : "3.10.14" 
}

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/68280'

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: 68280
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: 68280
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.

Path Parameters

job-id* string
The async job id.

Query Parameters

HTTP Headers

Responses

200 OK
cancel has been initiated.
400 Bad Request
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 Not Found
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/68473/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: 68473
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

[ 
  "68473" 
]


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

[ ]

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.

HTTP Headers

Responses

200 OK
is returned if the deletion operation was carried out successfully. This code will also be returned if no results were deleted.
400 Bad Request
is returned if job-id is not specified or has an invalid value.
404 Not Found
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 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: 68476
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=1712247108.7974308

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: 68477
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" : 1712247108.7974308 
}


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/68478

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: 68478
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

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.

HTTP Headers

Responses

200 OK
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 No Content
is returned if the job with the specified job-id is still in the queue of pending (or not yet finished) jobs.
400 Bad Request
is returned if you specified an invalid value for job-id or no value.
404 Not Found
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/68479

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: 68479
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/68480

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: 68480
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: 68482
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

[ 
  "68482", 
  "68479" 
]

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: 68483
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

[ 
  "68480" 
]

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/68484

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: 68484
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

[ 
  "68484", 
  "68480" 
]


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 
}