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

PUT /_db/{database-name}/_api/job/{job-id}

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.

Path Parameters
  • The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

  • The async job id.

Query Parameters
    HTTP Headers
      Responses
      • The job is still in the queue of pending (or not yet finished) jobs. In this case, no x-arango-async-id HTTP header is returned.

      • The job-id is missing in the request or has an invalid value. In this case, no x-arango-async-id HTTP header is returned.

          Response Body application/json object
        • The HTTP response status code.

        • A flag indicating that an error occurred.

        • A descriptive error message.

        • The ArangoDB error number for the error that occurred.

      • The job cannot be found or has already been deleted, or the result has already been fetched. In this case, no x-arango-async-id HTTP header is returned.

          Response Body application/json object
        • The HTTP response status code.

        • A flag indicating that an error occurred.

        • A descriptive error message.

        • The ArangoDB error number for the error that occurred.

      • 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

      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/68503'
      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' <<'EOF'
      {
        "name": " this name is invalid "
      }
      EOF
      
      curl -X PUT --header 'accept: application/json' --dump - 'http://localhost:8529/_api/job/68504'
      Show output

      Cancel an async job

      PUT /_db/{database-name}/_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 name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

      • The async job id.

      Query Parameters
        HTTP Headers
          Responses
          • The job cancellation has been initiated.

              Response Body application/json object
            • Always true.

          • The job-id is missing in the request or has an invalid value. In this case, no x-arango-async-id HTTP header is returned.

              Response Body application/json object
            • The HTTP response status code.

            • A flag indicating that an error occurred.

            • A descriptive error message.

            • The ArangoDB error number for the error that occurred.

          • The job cannot be found or has already been deleted, or the result has already been fetched. In this case, no x-arango-async-id HTTP header is returned.

              Response Body application/json object
            • The HTTP response status code.

            • A flag indicating that an error occurred.

            • A descriptive error message.

            • The ArangoDB error number for the error that occurred.

          Examples

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

          Delete async job results

          DELETE /_db/{database-name}/_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 name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

          • 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
            • The result of a specific job has been deleted successfully. This code is also returned if the deletion of all or expired jobs has been requested, including if no results were deleted.

                Response Body application/json object
              • Always true.

            • The job-id is missing in the request or has an invalid value. In this case, no x-arango-async-id HTTP header is returned.

                Response Body application/json object
              • The HTTP response status code.

              • A flag indicating that an error occurred.

              • A descriptive error message.

              • The ArangoDB error number for the error that occurred.

            • The job cannot be found or has already been deleted, or the result has already been fetched. In this case, no x-arango-async-id HTTP header is returned.

                Response Body application/json object
              • The HTTP response status code.

              • A flag indicating that an error occurred.

              • A descriptive error message.

              • The ArangoDB error number for the error that occurred.

            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=1730894177.1661682'
            
            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/68510'
            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 /_db/{database-name}/_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
            • The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

            • 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
              • The job has finished and you can fetch the result (the response has no body in this case), or your request for the list of pending or done jobs has been successful.

                  Response Body application/json
                • A list of job IDs. The list can be empty.

              • The job is still in the queue of pending (or not yet finished) jobs.

              • The job-id is missing in the request or has an invalid value. In this case, no x-arango-async-id HTTP header is returned.

                  Response Body application/json object
                • The HTTP response status code.

                • A flag indicating that an error occurred.

                • A descriptive error message.

                • The ArangoDB error number for the error that occurred.

              • The job cannot be found or has already been deleted, or the result has already been fetched. In this case, no x-arango-async-id HTTP header is returned.

                  Response Body application/json object
                • The HTTP response status code.

                • A flag indicating that an error occurred.

                • A descriptive error message.

                • The ArangoDB error number for the error that occurred.

              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/68511'
              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' <<'EOF'
              {
                "collections": {
                  "read": [
                    "_aqlfunctions"
                  ]
                },
                "action": "function () {require('internal').sleep(15.0);}"
              }
              EOF
              
              curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/job/68512'
              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' <<'EOF'
              {
                "collections": {
                  "read": [
                    "_frontend"
                  ]
                },
                "action": "function () {require('internal').sleep(15.0);}"
              }
              EOF
              
              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/68516'
              Show output