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
  • The async job id.

Query Parameters
    HTTP Headers
      Responses
      • 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.

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

      • 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

      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

      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/68501
      Show output

      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/68502
      Show output

      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
      • The async job id.

      Query Parameters
        HTTP Headers
          Responses
          • cancel has been initiated.

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

          • 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/68503/cancel
          
          curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
          Show output

          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
          • 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
          • A Unix timestamp specifying the expiration threshold for when the job-id is set to expired.

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

            • is returned if job-id is not specified or has an invalid value.

            • 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

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

            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/68508
            Show output

            Deleting the result of a non-existing job:

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

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

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

              • is returned if you specified an invalid value for job-id or no value.

              • 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/68509
              Show output

              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/68510
              Show output

              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

              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

              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/68514
              Show output