How to Call Long-running Functions Asynchronously

You can invoke long-running functions asynchronously using the doctl command line tool or the Functions REST API. You cannot run functions invoked as web functions asynchronously.

Asynchronous (or non-blocking) function invocations immediately return an activation ID, which you can then use to retrieve the function’s activation record, which includes the function’s output.

Synchronous (or blocking) function invocations are automatically converted to asynchronous if execution takes longer than 30 seconds. The converted function returns an activation ID and behaves exactly as if it had been called asynchronously from the start.

Call a Function Asynchronously using doctl

To call a function asynchronously using doctl, use the doctl serverless functions invoke command with the --no-wait flag:

doctl serverless functions invoke <your-function-name> --no-wait

Replace <your-function-name> with the name of your function, including the package name if necessary.

The command immediately returns a JSON object containing an activation ID:

{
  "activationId": "b68492d6875840148492d687586014f5"
}

The next section shows how to use this ID to retrieve the activation record.

Retrieve Activation Records Using doctl

Use the doctl serverless activation get command with an activation ID to retrieve the activation record:

doctl serverless activation get <your-activation-id>

Substitute your activation ID in this command.

If the function invocation is complete, it returns the full activation record as JSON. This record contains the output of the function along with other information about the process. See the Activation Record reference for more details.

{
  "namespace": "fn-378ae839-e58b-4cd1-afcf-632cd7b7b8db",
  "name": "sample/hello",
  "version": "0.0.1",
  "subject": "da25db4890885df62c1bfb6afdb4c91cb3b4bca5",
  "activationId": "b68492d6875840148492d687586014f5",
  "start": 1692623022053,
  "end": 1692623024056,
  "duration": 2002,
  "statusCode": 0,
  "response": {
    "status": "success",
    "statusCode": 0,
    "success": true,
    "result": {
      "body": "Hello stranger!"
    }
  },
  // ...
}

If the function is still running, the activation record does not yet exist and the command returns an error message. Additionally, the doctl command exits with an exit code of 1, indicating an error occurred:

Error: The requested activation record does not exist. This either means that the invocation is still running and the record is not yet created or the activation's retention period has already expired.

The retention period for activation records is at least 72 hours. If you see this error and your activation ID is less than 72 hours old, your function is still running and no activation record exists yet. Wait for your function to finish and then try again.

To retrieve only the response from your function with no additional process information, use result instead of get in the doctl command:

doctl serverless activation result <your-activation-id>

{
  "body": "Hello stranger!"
}

Both get and result support using the --last flag instead of specifying an activation ID. This returns the most recent activation record or result in the current namespace:

doctl serverless activation result --last

The command prints an activation header, followed by the result:

=== b68492d6875840148492d687586014f5 success 02/01 12:33:17 hello:0.0.12
{
  "body": "Hello stranger!"
}

To get only the result with no header, add the -q or --quiet flag:

doctl serverless activation result --last -q

The command prints the result only:

{
  "body": "Hello stranger!"
}

Call a Function Asynchronously using curl and the REST API

To call a function asynchronously using curl or any other HTTP client or library, use the Functions REST API. To find your function’s REST API URL, navigate to the function in the DigitalOcean Control Panel, then click the function’s Settings tab. The Access & Security section shows example curl commands for invoking the function.

To authenticate REST API requests, use a namespace access key. Create an access key, then use HTTP basic authentication with the access key ID as the username and the secret key as the password.

The following example invokes a function asynchronously by setting blocking=false:

curl -X POST "https://<api-host>/api/v1/namespaces/<your-namespace>/actions/sample/hello?blocking=false" \
  -H "Content-Type: application/json" \
  -u "<access-key-id>:<secret-key>"

Replace <api-host> and <your-namespace> with your function’s API host and namespace, and replace <access-key-id>:<secret-key> with your namespace access key credentials.

The Functions service immediately returns an activation ID:

{
  "activationId": "b68492d6875840148492d687586014f5"
}

You can get the activation record using doctl as shown in the previous section or use another REST API call as described in the following section.

Retrieve Activation Records Using curl and the REST API

To retrieve an activation record, send a GET request to the /activations/<your-activation-id> endpoint:

curl -X GET "https://<api-host>/api/v1/namespaces/<your-namespace>/activations/<your-activation-id>" \
  -u "<access-key-id>:<secret-key>"

If the function invocation is complete, the API returns the full activation record as JSON. This record contains the output of the function along with other information about the process. See the Activation Record reference for more details.

{
  "namespace": "fn-378ae839-e58b-4cd1-afcf-632cd7b7b8db",
  "name": "sample/hello",
  "version": "0.0.1",
  "subject": "da25db4890885df62c1bfb6afdb4c91cb3b4bca5",
  "activationId": "b68492d6875840148492d687586014f5",
  "start": 1692623022053,
  "end": 1692623024056,
  "duration": 2002,
  "statusCode": 0,
  "response": {
    "status": "success",
    "statusCode": 0,
    "success": true,
    "result": {
      "body": "Hello stranger!"
    }
  },
  // ...
}

If the function is still running, the activation record does not exist yet, and the API returns an error message:

{
  "code": "338d3285577add412cf6dee4e0a1fc9f",
  "error": "The requested activation record does not exist. This either means that the invocation is still running and the record is not yet created or the activation's retention period has already expired."
}

The retention period for activation records is 72 hours. If you see this error and your activation ID is less than 72 hours old, your function is still running and no activation record exists yet. Wait for your function to finish and then try again.

You can also list multiple recent activations by leaving the activation ID off of the URL. Optionally, you can limit the list size using ?limit=<number>. The following curl command lists the last three activations in the specified namespace:

curl -X GET "https://<api-host>/api/v1/namespaces/<your-namespace>/activations?limit=3" \
  -u "<access-key-id>:<secret-key>"

Retrieve Activation Records Using the Control Panel

You can also find activation records in the DigitalOcean Control Panel. Navigate to the Functions namespace containing your function, then click the Logs tab.

You can view all activations in the namespace or filter based on function name and time period. Click the [+] button next to an activation to see the full activation record details.