Automated Delivery

Automated Delivery is a functionality within the Tasking API that automates the delivery of satellite imagery assets to your storage destination once captures are published. This feature enables automatic delivery of captures and allows you to request additional deliveries and monitor the delivery status.

When an order is created, a delivery task is automatically created if the contract has support for auto-delivery.

Quick Start

Setting up Automated Delivery is simple:

1. Set up a destination - see the Destinations API documentation
2. Work with your Customer Success Manager (CSM) to get that destination configured as the destination for auto-delivery and to define default assets to be delivered
3. Start tasking and wait for your orders to arrive

The concepts and API endpoints described below allow for more fine-grained observability and control over the delivery process.

How Do I Know If My Order Was Delivered?

You can check the delivery status of your orders in several ways:

1. Check delivery task status - Use the GET /v2/delivery-tasks/ endpoint to list all delivery tasks and filter by order ID
2. Check individual delivery status - Use the GET /v2/deliveries/ endpoint and filter by order ID or capture ID
3. Monitor status changes - The status field in delivery tasks and deliveries will update as the delivery progresses through its lifecycle

Key Concepts

Automated Delivery follows a defined process for requesting and monitoring the delivery of imagery assets:

• Delivery Task: A request to deliver one or more captures to a specific destination
• Delivery: A specific capture being delivered as part of a delivery task

Delivery Task Lifecycle

Delivery tasks follow a status lifecycle:

1. PENDING: Initial state when a delivery task is created
2. IN_PROGRESS: At least one delivery has been requested but not all are complete
3. COMPLETED: All deliveries have been successfully completed
4. FAILED: One or more deliveries have failed
5. CANCELLED: The task has been cancelled

Delivery Lifecycle

Individual deliveries follow their own status lifecycle:

1. PENDING: Initial state when a delivery is created
2. REQUESTED: Delivery request has been sent to the delivery service
3. COMPLETED: All expected assets have been delivered successfully
4. FAILED: Some expected assets failed to deliver
5. CANCELLED: The delivery has been cancelled

Requesting Additional Deliveries

To request additional an delivery of captures, make a POST request to the /v2/delivery-tasks/ endpoint. The request requires a list of capture IDs for the captures you want to deliver.

CURL

curl --request POST 'https://api.planet.com/tasking/v2/delivery-tasks/' \
--header 'Accept: application/json' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "capture_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "delivery_destination_id": "my-destination-id",
  "requested_asset_types": ["ortho_visual", "basic_analytic"]
}'

Request Parameters

Parameter	Required	Description
capture_ids	Yes	Array of UUIDs for the captures to be delivered
delivery_destination_id	No	Destination ID for delivery. If not provided, will use the auto_delivery_destination_id from the order
requested_asset_types	No	Array of asset types to deliver. If not provided, will use the asset types from the order

Response

[
  {
    "id": "12345-e89b-12d3-a456-426614174000",
    "order_id": "67890-e89b-12d3-a456-426614174000",
    "delivery_destination_id": "my-destination-id",
    "requested_asset_types": ["ortho_visual", "basic_analytic"],
    "status": "PENDING",
    "created_time": "2023-09-15T12:26:36.137220Z",
    "updated_time": "2023-09-15T12:26:36.137259Z",
    "deliveries": ["12345-e89b-12d3-a456-426614174000"]
  }
]

Retrieving Delivery Tasks

To get a list of all your delivery tasks, make a GET request to the /v2/delivery-tasks/ endpoint:

CURL

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

Filtering

You can filter delivery tasks by:

• status
• created_time
• updated_time
• order_id
• delivery_destination_id
• delivery_completed_time

Example:

CURL

curl --request GET \
--url 'https://api.planet.com/tasking/v2/delivery-tasks/?status=COMPLETED&created_time__gt=2023-01-01T00:00:00Z' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json'

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "12345-e89b-12d3-a456-426614174000",
      "order_id": "67890-e89b-12d3-a456-426614174000",
      "delivery_destination_id": "my-destination-id",
      "requested_asset_types": ["ortho_visual", "basic_analytic"],
      "status": "COMPLETED",
      "delivery_completed_time": "2023-09-15T14:30:45.123456Z",
      "created_time": "2023-09-15T12:26:36.137220Z",
      "updated_time": "2023-09-15T14:30:45.123456Z",
      "deliveries": ["12345-e89b-12d3-a456-426614174000"]
    }
  ]
}

Retrieving Deliveries

To get details about specific deliveries, make a GET request to the /v2/deliveries/ endpoint:

CURL

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

Filtering

You can filter deliveries by:

• status
• created_time
• updated_time
• delivery_task_id
• capture_id
• order_id
• delivery_completed_time

Example:

CURL

curl --request GET \
--url 'https://api.planet.com/tasking/v2/deliveries/?status=COMPLETED&delivery_task_id=12345-e89b-12d3-a456-426614174000' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json'

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "12345-e89b-12d3-a456-426614174000",
      "order_id": "67890-e89b-12d3-a456-426614174000",
      "capture_id": "123e4567-e89b-12d3-a456-426614174000",
      "delivery_task_id": "12345-e89b-12d3-a456-426614174000",
      "expected_asset_types": ["ortho_visual", "basic_analytic"],
      "status": "COMPLETED",
      "delivery_completed_time": "2023-09-15T14:30:45.123456Z",
      "created_time": "2023-09-15T12:26:36.137220Z",
      "updated_time": "2023-09-15T14:30:45.123456Z",
      "item_assets": [
        {
          "id": "12345-e89b-12d3-a456-426614174000",
          "item_id": "20230915_085131_12_1234",
          "item_type": "SkySatCollect",
          "delivered_asset_types": ["ortho_visual", "basic_analytic"],
          "failed_asset_types": null
        }
      ]
    }
  ]
}

Limitations

1. Capture Status: Only captures in the PUBLISHED state can be delivered.
2. Asset Types: Only asset types applicable to the satellite type of the capture can be delivered.
3. Destinations: A valid delivery destination must be configured.

info

For more information about delivery destinations, please refer to the Destinations API documentation.