Automated Delivery

Automated Delivery is a functionality within the Tasking API that makes your imagery assets available automatically once captures are published, without you having to request each one. It also lets you monitor delivery status and, for cloud deliveries, request additional deliveries.

Delivery Options

There are two ways to receive your assets, plus the option to turn Automated Delivery off:

Option	What happens	Requires
Download links	Assets are activated as soon as a capture is published and can be downloaded as a single ZIP file from the Tasking Dashboard.	Nothing to configure.
Deliver to destination	Assets are delivered automatically to your cloud storage bucket.	A configured cloud destination.
No delivery	No Automated Delivery is initiated. Access your assets through other routes, such as the Orders API.	—

The delivery option is a per-user setting: it applies to every order you create while it is set, and changing it does not affect orders you have already placed.

Setting Your Delivery Option

In the Tasking Dashboard

Open Settings > Data and select one of the options under Delivery option. The change is saved as soon as you select it and affects only future orders.

Through the Tasking API

Make a PUT request to the /v2/preferences/ endpoint with the option you want:

CURL

curl --request PUT 'https://api.planet.com/tasking/v2/preferences/' \
--header 'Accept: application/json' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "delivery_option": "DIRECT_DOWNLOAD"
}'

Value	Dashboard label
`DIRECT_DOWNLOAD`	Download links
`CLOUD_DESTINATION`	Deliver to destination
`NONE`	No delivery

To check which option is currently set, make a GET request to the same endpoint:

CURL

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

note

Automated Delivery also requires asset types to be set on the order. Orders whose imagery publishing is delayed, such as imagery subject to regional restrictions, are excluded from Automated Delivery.

Quick Start

Enabling download links

Set your delivery option to Download links.
Start tasking. When a capture is published, its assets are activated automatically.
Download the capture as a ZIP file from the Tasking Dashboard. See Direct Download.

There is nothing else to configure: download links need no destination, no bucket, and no credentials.

Enabling delivery to a destination

Create and manage your destination in the Destinations UI. See the Destinations API documentation for details.
Set your delivery option to Deliver to destination.
Start tasking and wait for your orders to arrive.

Orders use your organization's default destination unless you override it. See Configuring Cloud Delivery on Order Create.

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

Direct Download

When your delivery option is Download links, Planet activates your assets as soon as a capture is published, and you download them yourself from the Tasking Dashboard. No cloud storage and no destination configuration is required.

How it works

A capture in your order reaches the PUBLISHED state.
Planet activates the requested asset types for that capture. While this is in progress the Tasking Dashboard shows Assets are being prepared for download.
Once every asset is active, the capture becomes downloadable, the delivery task moves to the ACTIVATED status, and the dashboard shows Assets are ready for download.
You download the capture's assets as a single ZIP file from the capture detail view.

You can check whether a capture is ready to download through the API with the downloadable field on the capture:

CURL

curl --request GET \
--url 'https://api.planet.com/tasking/v2/captures/?order_id=67890-e89b-12d3-a456-426614174000&downloadable=true' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json'

Availability window

Activated assets remain downloadable for 14 days. When that window closes, downloadable returns to false, the capture can no longer be downloaded from the dashboard, and a DELIVERY_TASK_DIRECT_DOWNLOAD_EXPIRED event is added to your order history.

You can download the same capture as many times as you like while the window is open.

Limitations

Tasking Dashboard only. There is no Tasking API endpoint that returns a download link. The Tasking API tells you whether a capture is downloadable; the download itself happens in the dashboard.
SkySat collects only. SkySat scenes are not included in direct download. Order them through the Orders API if you need them.
No destination or path prefix. Both apply to cloud delivery only and are ignored for direct download orders.
No redelivery. The /v2/delivery-tasks/ endpoint delivers to a cloud destination, so it cannot be used to re-activate a direct download. Assets can be re-downloaded any time within the 14-day window instead.
No processing tools. Assets are delivered as captured. For clipping, band math, or format conversion, use the Orders API tools.

Configuring Cloud 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/<id>`, 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. See the Destinations API documentation for managing destinations.

Inspecting an Order's Delivery Configuration

An order reports the delivery settings it was created with. GET /v2/orders/{id}/ returns a read-only delivery_option alongside the delivery block:

{
  "id": "67890-e89b-12d3-a456-426614174000",
  "name": "Order 01",
  "delivery_option": "CLOUD_DESTINATION",
  "delivery": {
    "delivery_option": "CLOUD_DESTINATION",
    "destination": {
      "ref": "pl:destinations/my-s3-destination-CKxV9io",
      "path_prefix": "planet-scenes"
    }
  }
}

For a direct download order there is no destination, so the destination block is omitted:

"delivery": {
  "delivery_option": "DIRECT_DOWNLOAD"
}

You can also list orders by the delivery option they were created with:

CURL

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

note

delivery_option is fixed on the order at creation time from your user preference. Changing your preference afterwards does not change existing orders, and the option cannot be set in the order payload.

How Do I Know If My Order Was Delivered?

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

Check delivery task status - Use the GET /v2/delivery-tasks/ endpoint to list all delivery tasks and filter by order ID
Check individual delivery status - Use the GET /v2/deliveries/ endpoint and filter by order ID or capture ID
Monitor status changes - The status field in delivery tasks and deliveries will update as the delivery progresses through its lifecycle
Check whether a capture is downloadable - For direct download orders, the downloadable field on the capture tells you when its assets are ready

Key Concepts

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

Delivery Task: A request to make one or more captures available, either at a specific cloud destination or for direct download
Delivery: A specific capture being delivered as part of a delivery task

One delivery task is created per tasking task, and it holds one delivery per fulfilling capture. A stereo order therefore produces a single delivery task with two or three deliveries under it.

The delivery_option field on a delivery task tells you which route it took: CLOUD_DESTINATION or DIRECT_DOWNLOAD.

Delivery Task Lifecycle

Delivery tasks follow a status lifecycle:

PENDING: Initial state when a delivery task is created
IN_PROGRESS: At least one delivery has been requested but not all are complete
COMPLETED: All deliveries to a cloud destination have been successfully completed
ACTIVATED: All assets for a direct download have been activated and the captures are downloadable. This is the direct download equivalent of COMPLETED
FAILED: One or more deliveries have failed
CANCELLED: The task has been cancelled
EXPIRED: The delivery window has closed. For direct download, the captures are no longer downloadable

A delivery task for a cloud destination is created directly in FAILED if the order has no destination that can be resolved at the time the task is created. In that case no delivery is attempted.

Delivery Lifecycle

Individual deliveries follow their own status lifecycle:

PENDING: Initial state when a delivery is created
REQUESTED: Delivery request has been sent to the delivery service
COMPLETED: All expected assets have been delivered successfully to a cloud destination
ACTIVATED: All expected assets have been activated for direct download
FAILED: Some expected assets failed to deliver
CANCELLED: The delivery has been cancelled
EXPIRED: The delivery window has closed

Requesting Additional Deliveries

Additional deliveries apply to cloud destinations only. For direct download orders, re-download the capture from the Tasking Dashboard instead.

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/<id>` 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_option": "CLOUD_DESTINATION",
    "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:

Field	Supported lookups
`id`	`exact`, `in`, `ne`, `notin`
`status`	`exact`, `in`, `ne`, `notin`
`delivery_destination_id`	`exact`, `in`, `ne`, `notin`
`order_id`	`exact`, `in`
`delivery_completed_time`	`exact`, `gt`, `gte`, `lt`, `lte`

Append the lookup to the field name with a double underscore, for example delivery_completed_time__gte. Using exact needs no suffix.

Example:

CURL

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

note

Query parameters that are not in the table above are ignored rather than rejected, so a misspelled filter silently returns unfiltered results.

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "12345-e89b-12d3-a456-426614174000",
      "order_id": "67890-e89b-12d3-a456-426614174000",
      "delivery_option": "CLOUD_DESTINATION",
      "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:

Field	Supported lookups
`id`	`exact`, `in`, `ne`, `notin`
`status`	`exact`, `in`, `ne`, `notin`
`delivery_task_id`	`exact`, `in`
`capture_id`	`exact`, `in`
`order_id`	`exact`, `in`
`delivery_completed_time`	`exact`, `gt`, `gte`, `lt`, `lte`

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

Capture Status: Only captures in the PUBLISHED state can be delivered.
Asset Types: Only asset types applicable to the satellite type of the capture can be delivered, and asset types must be set on the order.
Destinations: For cloud delivery, a valid delivery destination must be configured. If the destination you supply on order create cannot be resolved, the order is created without Automated Delivery rather than being rejected.
Delayed publishing: Orders with delayed imagery publishing are excluded from Automated Delivery.

info

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

Delivery Options​

Setting Your Delivery Option​

In the Tasking Dashboard​

Through the Tasking API​

Quick Start​

Enabling download links​

Enabling delivery to a destination​

Direct Download​

How it works​

Availability window​

Limitations​

Configuring Cloud Delivery on Order Create​

Delivery Parameters​

Inspecting an Order's Delivery Configuration​

How Do I Know If My Order Was Delivered?​

Key Concepts​

Delivery Task Lifecycle​

Delivery Lifecycle​

Requesting Additional Deliveries​

Request Parameters​

Response​

Retrieving Delivery Tasks​

Filtering​

Response​

Retrieving Deliveries​

Filtering​

Response​

Limitations​

Delivery Options

Setting Your Delivery Option

In the Tasking Dashboard

Through the Tasking API

Quick Start

Enabling download links

Enabling delivery to a destination

Direct Download

How it works

Availability window

Limitations

Configuring Cloud Delivery on Order Create

Delivery Parameters

Inspecting an Order's Delivery Configuration

How Do I Know If My Order Was Delivered?

Key Concepts

Delivery Task Lifecycle

Delivery Lifecycle

Requesting Additional Deliveries

Request Parameters

Response

Retrieving Delivery Tasks

Filtering

Response

Retrieving Deliveries

Filtering

Response

Limitations