Skip to main content

Notification and History

Managing Your Tasking Orders​

A Tasking Order, as it progresses through the Tasking API system, passes through a number of states triggered by external events, such as publishing a collected imagery or confirmation of an imaging window allockation. Each Tasking Order keeps a history of these transitions, and you can be notified of these transitions as they happen in real time.

Tasking Order History​

You can review the history of your orders and their captures directly from the API using the endpoint:

https://api.planet.com/tasking/v2/order-history

This endpoint can accept a number of filters, which will help you find and process the history events that matter to you. The following example will request all history events that are other ORDER_CREATED or ORDER_FULFILLED:

curl --request GET \
--url 'https://api.planet.com/tasking/v2/order-history/?event_type__in=ORDER_CREATED%2CORDER_FULFILLED' \
--header "Authorization: api-key $PL_API_KEY" \
--header "Content-Type: application/json"

More information about what filters can be applied to the history requests can be found in the tasking history API reference.

Email Notifications​

As your Tasking Order transitions from one state to the next, you can receive notifications by email. Notifications inform you of the progress versus monitoring the Tasking Dashboard or making calls to the Tasking API for status information. The emails are sent to the email address of the user that the API key used in the requests refers to. It is not possible to direct these notification emails to another email address.

You will not receive emails until you grant permissions for Planet to send you email notifications, and you can do this either through the Tasking Dashboard or by using the Tasking API. To achieve this using the Tasking API, it requires a POST request being made to the /v2/preferences/notifications/ endpoint:

curl --request POST \
--url https://api.planet.com/tasking/v2/preferences/notifications \
--header "Authorization: api-key $PL_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "enabled_emails": [
    "ORDER_CREATED"
  ]
}'

The above POST request allows the Tasking API to send an email each time a Tasking Order is created using the same API key as what was used to set the notification permissions. Email notifications can be set up for the following events in the Tasking system:

ORDER_FULFILLED,
ORDER_EXPIRED,
ORDER_CREATED,
CAPTURE_FAILED,
CAPTURE_PUBLISHED,
CAPTURE_SCHEDULED,
ORDER_LOCK_IN_CONFIRMED,
ORDER_LOCK_IN_CANCELLATION_FAILED,
ORDER_LOCK_IN_FAILED,
BULK_FINISHED

The POST request to the /v2/preferences/notifications endpoint works as a switch for each event in the above list. In other words, if an event is included in the request, notifications are either enabled for that event OR if that notifications were already enabled, then they stay enabled. If an event is excluded from the POST event then notifications for that event are then disabled. To see what notification preferences have been set, make a GET request to the same endpoint:

curl --request GET \
--url https://api.planet.com/tasking/v2/preferences/notifications \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json'

This will return a response that will look similar to this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "enabled_emails": [
        "ORDER_CREATED"
      ]
    }
  ]
}

It is not possible to have different notification settings per Tasking Order, so the notifications that you choose to receive will apply to every order you create.

info

For more information, please refer to the Notification API Reference.

If you want to do the initial set up using the Tasking Dashboard, or learn about features of the Tasking Dashboard, refer to the Tasking Dashboard documentation.

Last updated on