---
title: "Scripting API tasks with the notification parameter"
date: "2024-02-14T06:18:38+00:00"
summary: "Streamline API task scripting with notification parameters. Learn to track progress, handle responses, and automate database creation using the Cloud Platform API's notification system for efficient task management."
image:
type: "page"
url: "/acquia-cloud-platform/scripting-api-tasks-notification-parameter"
id: "bb491f2f-b42e-4ee3-9ef9-0d0013a7dfc3"
---

Endpoints in the [Cloud Platform API](/acquia-cloud-platform/develop-apps/api) containing a [notificationUuid](https://cloudapi-docs.acquia.com/#/Notifications/getNotificationByUuid) field in returned results enable you to determine the progress and completion status of ongoing tasks. The following general steps describe how you can use the notification parameter:

1.  Issue a Cloud Platform API request to an endpoint that includes a `notificationUuid` value in the returned result.
2.  Use the returned `notificationUuid` value in a request to the [GET /notifications/{notificationUuid}](https://cloudapi-docs.acquia.com/#/Notifications/getNotificationByUuid) endpoint to retrieve current information about the status of your task.

Note

The notification API doesn’t display real-time results. It typically returns a response within seconds, but sometimes can take several minutes to reflect the current state of the platform.

Endpoint example values and schemas
-----------------------------------

An API request to [deploy a build artifact to an environment](https://cloudapi-docs.acquia.com/#/Environments/postDeployArtifact) returns a result similar to the following example, which includes a `notification` value:

    {
    "message": "Deploying artifact.",
    "_links": {
        "self": {
        "href": "https://cloud.acquia.com/api/environments/666-99999999-zzzz-4444-aaaa-444444444444/artifacts/actions/switch"
                },
        "notification": {
        "href": "https://cloud.acquia.com/api/notifications/1111111-7777-4444-aaaa-555555555555"
        }
    }
    }

You can use the `notification` value to query the [GET /notifications/{notificationUuid}](https://cloudapi-docs.acquia.com/#/Notifications/getNotificationByUuid) endpoint, which returns data in the following structure:

    {
    "uuid": "1111111-7777-4444-aaaa-555555555555",
    "event": "ApplicationAddedToRecents",
    "label": "Application added to recents list",
    "description": "\"App Name\" was added to your recent applications list.",
    "created_at": "2019-07-29T20:47:13+00:00",
    "completed_at": "2019-07-29T20:47:13+00:00",
    "status": "completed",
    "progress": 100,
    "context": {
        "author": {
        "uuid": "55555555-dddd-4444-8888-777777777777",
        "actual_uuid": "55555555-dddd-4444-8888-777777777777"
        },
        "user": {
        "uuids": [
            "55555555-dddd-4444-8888-777777777777"
        ]
        }
    },
    "_links": {
        "self": {
        "href": "https://cloud.acquia.dev/api/notifications/1111111-7777-4444-aaaa-555555555555"
        },
        "parent": {
        "href": "https://cloud.acquia.dev/api/notifications"
        }
    }
    }

The response includes (but isn’t limited to) the following fields:

*   `progress`: An integer between 1 and 100, which is an estimate of the completion percentage of the task.
*   `status`: A string (either `completed` or `in_progress`) describing the completion state of the task.
*   `created_at`: The creation date and time the notification.
*   `started_at`: The starting date and time for the task or event tracked by this notification.
*   `completed_at`: The completion date and time for the task or event tracked by this notification.

For a complete list of returned fields and their definitions, see the [Cloud Platform API endpoint documentation](https://cloudapi-docs.acquia.com/#/Notifications/getNotificationByUuid).

Example script
--------------

The following [`database creation example script`](/node/55797#api-notification-example) performs the following tasks:

*   Creates a database.
*   Retrieves the notification ID from the response.
*   Determines the status of the notification.
*   Displays a message when the notification indicates the task is complete.

    <?php
    
    // This example requires `league/oauth2-client` package.
    // Run `composer require league/oauth2-client` before running.
    require __DIR__ . '/vendor/autoload.php';
    
    use League\OAuth2\Client\Provider\GenericProvider;
    use GuzzleHttp\Client;
    
    // The UUID of an application you want to create the database for.
    $applicationUuid = 'APP-UUID';
    $dbName = 'test_database_1';
    // See https://docs.acquia.com/cloud-platform/develop/api/auth/
    // for how to generate a client ID and Secret.
    $clientId = 'API-KEY';
    $clientSecret = 'API-SECRET';
    
    $provider = new GenericProvider([
        'clientId'                => $clientId,
        'clientSecret'            => $clientSecret,
        'urlAuthorize'            => '',
        'urlAccessToken'          => 'https://accounts.acquia.com/api/auth/oauth/token',
        'urlResourceOwnerDetails' => '',
    ]);
    
    $client = new Client();
    $provider->setHttpClient($client);
    
    echo 'retrieving access token', PHP_EOL;
    $accessToken = $provider->getAccessToken('client_credentials');
    echo 'access token retrieved', PHP_EOL;
    
    // Generate a request object using the access token.
    $request = $provider->getAuthenticatedRequest(
        'POST',
        "https://cloud.acquia.com/api/applications/{$applicationUuid}/databases",
        $accessToken,
        [
            'headers' => ['Content-Type' => 'application/json'],
            'body' => json_encode(['name' => $dbName])
        ]
    );
    
    // Send the request.
    echo 'requesting db create api', PHP_EOL;
    $response = $client->send($request);
    
    echo 'response parsing', PHP_EOL;
    $responseBody = json_decode($response->getBody()->getContents(), true);
    
    $notificationLink = $responseBody['_links']['notification']['href'];
    
    $retryCount = 10;
    
    echo 'start watching for notification status at ', $notificationLink, PHP_EOL;
    do {
        sleep(5);
        // create notification request.
        $request = $provider->getAuthenticatedRequest(
            'GET',
            $notificationLink,
            $accessToken
        );
    
        echo 'requesting notification status', PHP_EOL;
        $response = $client->send($request);
        $responseBody = json_decode($response->getBody()->getContents(), true);
        echo 'notification status: ', $responseBody['status'], PHP_EOL;
    
        if ($responseBody['status'] === 'succeeded') {
            echo 'Successfully created database.';
            exit(0);
        } elseif ($responseBody['status'] === 'failed') {
            echo 'Failed to create database.';
            exit(1);
        } else {
            echo 'retrying notification in 5 sec', PHP_EOL;
            $retryCount--;
            $retry = $retryCount > 0;
        }
    } while ($retry);