Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/tasking/auto_delivery/) # 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. Work with the Tech Support team to opt in to Automated Delivery by submitting a support ticket through the [Planet Support](https://support.planet.com/hc/en-us) 2. Set up a destination - see the [Destinations API documentation](https://docs.planet.com/develop/apis/destinations.md) 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. ## Configuring Automated Delivery on Order Create You can configure the destination and an optional `path_prefix` for Automated Delivery when creating a Tasking order by including a `delivery` block in the order payload. Once set, every delivery generated by that order — including redeliveries — inherits these settings unless explicitly overridden. * CURL ``` curl --request POST 'https://api.planet.com/tasking/v2/orders/' \ --header 'Accept: application/json' \ --header "Authorization: api-key $PL_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "Order 01", "geometry": { "type": "Point", "coordinates": [149.44135, 28.49240] }, "delivery": { "destination": { "ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "planet-scenes" } } }' ``` To deliver to your organization's default destination, use the `default` alias: ``` "delivery": { "destination": { "ref": "pl:destinations/default", "path_prefix": "planet-scenes" } } ``` ### Delivery Parameters | Parameter | Required | Description | | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `delivery.destination.ref` | Yes | Destination reference in the form `pl:destinations/`, or `pl:destinations/default` to use the organization's default destination. | | `delivery.destination.path_prefix` | No | Optional string prepended to delivered files. Allowed characters: letters (Unicode included), digits, and `_ - . / +`. A forward slash (`/`) is treated as a folder; cannot be at the start or end. Max 128 bytes (UTF-8). | | `auto_delivery_destination_id` | — | **Deprecated.** Use `delivery.destination.ref` instead. Will be removed in a future version. Supplying both shapes with conflicting values will be rejected. | info The `delivery` block follows the same shape used by the [Orders API delivery destinations](https://docs.planet.com/develop/apis/orders/delivery.md#destinations). See the [Destinations API documentation](https://docs.planet.com/develop/apis/destinations.md) for managing destinations. ## 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 an additional 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": { "ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "redelivery/run-2" } }, "requested_asset_types": ["ortho_visual", "basic_analytic"] }' ``` If the `delivery` block is omitted, the redelivery reuses the destination and `path_prefix` of the original delivery task for those captures. Supplying `delivery` overrides those settings for this redelivery only. A redelivery to the same destination but a different `path_prefix` (or different asset types) is allowed; uniqueness is enforced on the `(destination, path_prefix, assets, capture)` tuple. ### Request Parameters | Parameter | Required | Description | | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capture_ids` | Yes | Array of UUIDs for the captures to be delivered. | | `delivery.destination.ref` | No | Destination reference (`pl:destinations/` or `pl:destinations/default`). If omitted, inherits from the original delivery task. | | `delivery.destination.path_prefix` | No | Optional string prepended to delivered files. Same format rules as on order create (letters, digits, `_ - . / +`; no leading/trailing `/`; max 128 bytes UTF-8). If omitted, inherits from the original delivery task. | | `requested_asset_types` | No | Array of asset types to deliver. Uses the asset types from the order if omitted. | warning The flat `delivery_destination_id` field is deprecated and will be removed in a future version. Use the nested `delivery.destination.ref` shape instead. ### Response ``` [ { "id": "12345-e89b-12d3-a456-426614174000", "order_id": "67890-e89b-12d3-a456-426614174000", "delivery_destination_id": "my-destination-id", "pl_ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "redelivery/run-2", "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", "pl_ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "planet-scenes", "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](https://docs.planet.com/develop/apis/destinations.md).