Keeping track of your tasking orders past and present¶
A Tasking Order, as it progresses through the Tasking API system, passes through a number of states as shown on the overview page. 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¶
To find out more about Tasking Order history on the Tasking Dashboard, go here
However, if you are reading this you probably want to know how to do this via the API. 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 <YOUR_API_KEY>' \
--header 'content-type: application/json'
More information about what filters can be applied to the history requests can be found in the Order History API Reference
Email Notifications¶
As your Tasking Order transitions from one state to the next, it is possible to receive notifications by email, informing you of its progress so you can be kept up-to-date without having to constantly come back to the Tasking Dashboard or having to make calls to the Tasking API to know the state of your Tasking order. The inbox to which these emails are sent is 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 won't receive emails until you grant permissions for Planet to send you email notifications, and you can do this either via 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 <YOUR_API_KEY>' \
--header 'content-type: application/json' \
--data '{
"enabled_emails": [
"ORDER_CREATED"
]
}'
The above POST request tells 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
NOTE 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 <YOUR_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.
For more information, please refer to the Notification API Reference.
If you want to do the initial set up via the Tasking Dashboard, you can find out more about that and other features of the Tasking Dashboard here
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.