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

Return result of an async job

fetches a job result and removes it from the queue

PUT /_api/job/{job-id}

Path Parameters

  • job-id (string, required): The async 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

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:

shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job

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
Show response body

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

shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere

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
Show response body

Fetching the result of an HTTP GET job:

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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: 84540
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84540

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: 61
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: 84540
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Fetching the result of an HTTP POST job that failed:

shell> 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

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: 84542
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84542

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: 84542
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Cancel async job

cancels an async job

PUT /_api/job/{job-id}/cancel

Path Parameters

  • job-id (string, required): The async job id.

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

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

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

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: 84527
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending

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
shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84527/cancel

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
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending

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
Show response body

Deletes async job

deletes an async job result

DELETE /_api/job/{job-id}

Path Parameters

  • job-id (string, required): 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, optional): A Unix timestamp specifying the expiration threshold for when the job-id is set to expired.

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.

Responses

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 job-id is not specified or has an invalid value.

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

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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: 84531
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all

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
Show response body

Deleting expired jobs:

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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: 84533
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time

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
shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1680612470.4825256

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
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending

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
Show response body

Deleting the result of a specific job:

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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: 84535
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84535

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
Show response body

Deleting the result of a non-existing job:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere

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
Show response body

List async jobs by status or get status of specific job

Returns the ids of job results with a specific status or the status of a specific job

GET /_api/job/{job-id}

Path Parameters

  • job-id (string, required): 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, optional): 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.

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

Responses

HTTP 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).

HTTP 204: is returned if the job with the specified job-id is still in the queue of pending (or not yet finished) jobs.

HTTP 400: is returned if you specified an invalid value for job-id or no value.

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

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84551

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…)

shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : [ 
      "_aqlfunctions" 
    ] 
  }, 
  "action" : "function () {require('internal').sleep(15.0);}" 
}
EOF

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

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84553

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:

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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: 84544
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done

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
Show response body

Fetching the list of pending jobs:

shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version

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

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending

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

[ ]

Fetching the list of a pending jobs while a long-running job is executing (and aborting it):

shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : [ 
      "_frontend" 
    ] 
  }, 
  "action" : "function () {require('internal').sleep(15.0);}" 
}
EOF

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: 84548
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending

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
shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/84548

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
Show response body
❮  Foxx

© ArangoDB - Graph and Beyond