There are some API actions that take too long to be completed synchronously (i.e. returned immediately) in an HTTP Request. We refer to such actions as asynchronous and have a shared pattern for API endpoints when handling them.
The pattern consists of a pair of endpoints for each asynchronous action, one for initiating the action (Run) and another for querying the status of previously started actions (Status). It also consists of webhook calls to proactively notify you once an action completes. The following sections will go into detail for each of these.
Run
Each asynchronous action will have an endpoint ending in /run to initiate the action. The endpoint will generally follow the pattern POST /tenants/{tenant_id}/.../{action_name}/run.
The endpoint will do a preliminary check of request inputs and return either:
-
202 Accepted: If the preliminary check passes and the job was successfully kicked off. This does not indicate that the job will succeed, merely that all the inputs were properly formed. -
422 Unprocessable Entity: If the preliminary check failed. The response will include a message indicating what part of the request inputs need to be modified.
This endpoint will take different request inputs depending on the action, so refer to the specific endpoint section in the API doc for more information. See the Currently Supported Asynchronous Endpoints section below for a list of endpoints and their respective sections in the doc.
Given an accepted request, the response body will include a job_id field which represents the asynchronous job that was initiated. Take note of this id as it is required to query the status of the job.
Status
After initiating an asynchronous action, you may check the status of the action using the /status endpoint. The endpoint will generally follow the pattern of GET /tenants/{tenant_id}/.../{action_name}/status?job_id={job_id} where job_id is the id returned from the /run endpoint.
You can also query jobs that you did not initiate via the API using this endpoint if you know the job_id. (Ex. if you get a job_id back from a webhook that was initiated from a UI action)
The endpoint will return a summary of metadata for the job, including but not limited to the status of the job and any results/errors. This summary is ephemeral for each job and only exists for a max of 7 days before they will not be returned from this endpoint.
Webhooks
In addition to the /status endpoint, Aurora also allows enterprise clients to receive webhook calls on completion of an async job. This replaces the need to constantly query the /status endpoint in a loop.
The webhook call will include the ID of the job and the status (and potentially other metadata unique to the endpoint), allowing you to automate actions on job success or failure. If the status is failed, then you can query the /status endpoint for detailed error messages.
To set up a webhook, refer to the Webhooks suite of APIs.
Multiple authentication mechanisms are available e.g. HTTP basic auth and secret HTTP headers.