Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/orders/reference/) # Orders API Reference * Orders * getList Orders * postCreate Order * getGet Order * putCancel an order * postCancel Orders in bulk * getAggregated Order Stats * getDownload Order * getGet OpenAPI spec * getGet json spec for product bundles * getGet compatibility specification for item types, bundles, and tools [API docs by Redocly](https://redocly.com/redoc/) # Planet Orders API (2.0.0) Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/orders-api-spec.yaml) The Orders API permits complex asset orders. ## [](#tag/Orders)Orders ## [](#tag/Orders/operation/listOrders)List Orders Returns all order requests. ##### Authorizations: *BasicAuth**ApiKeyAuth* ##### query Parameters | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_marker | stringPaging marker. | | page\_size | integerNumber of orders per page. | | state | Array of stringsItems Enum: "queued" "running" "failed" "success" "partial" "cancelled"Filter orders by state on ListOrders. Accepts multiple values treated as a logical OR via multiple query parameters, e.g. ?state=queued\&state=running. | | source\_type | Array of stringsFilter orders by source\_type (scenes and/or basemaps) on ListOrders. Accepts multiple values treated as a logical OR via:1. comma-separated list, e.g. ?source\_type=scenes,basemaps
2. multiple query parameters, e.g. ?source\_type=scenes\&source\_type=basemaps All source types can be included with ?source\_type=all. Defaults to only returning scenes orders for backwards-compatibility. | | name | stringFilter orders by name | | name\_\_contains | stringFilter orders by name containing a string | | created\_on | stringFilter orders by created\_on interval or instant. The time can be a closed interval (e.g. `2024-01-01T00:00:00.00Z/2024-02-01T00:00:00.00Z` for the month of January), an open interval (e.g. `2024-01-01T00:00:00.00Z/..` for all results in January or later and `../2024-01-01T00:00:00.00Z` for all results before January), or an instant (e.g. `2024-01-01T00:00:00.00Z`). Start times for intervals are inclusive, and end times are exclusive. | | last\_modified | stringFilter orders by last\_modified interval or instant. The time can be a closed interval (e.g. `2024-01-01T00:00:00.00Z/2024-02-01T00:00:00.00Z` for the month of January), an open interval (e.g. `2024-01-01T00:00:00.00Z/..` for all results in January or later and `../2024-01-01T00:00:00.00Z` for all results before January), or an instant (e.g. `2024-01-01T00:00:00.00Z`). Start times for intervals are inclusive, and end times are exclusive. | | hosting | booleanOnly return orders that contain a hosting block (e.g. Planet Insights Platform hosting) | | sort\_by | stringFields to sort orders by. Multiple fields can be specified separated by commas. The sort direction can be specified by appending ' ASC' or ' DESC' to the field name. The default sort direction is ascending.When multiple fields are specified, the sort order is applied in the order the fields are listed.If no `sort_by` parameter is provided, orders will be sorted by `created_on DESC` by default.Supported fields: name, created\_on, state, last\_modifiedExamples:- `sort_by=name`
- `sort_by=name DESC`
- `sort_by=name,state DESC,last_modified` | | destination\_ref | stringOnly return orders that were created with a given destination reference (e.g. pl:destinations/...) | | user\_id | stringFilter orders by user. Only admin users can use this parameter. Valid values are 'all' (to view all orders in the organization) or a specific user ID. If not provided, defaults to showing only orders created by the requesting user. | ### Responses **200** A list of Order requests. **400** Invalid request. **401** Access denied - insufficient privileges. **500** Server Error. **default** Other error. get/orders/v2 https\://api.planet.com/compute/ops/orders/v2 ### Response samples * 200 * 400 * 401 * 500 * default Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "next": "string" }, "orders": [ { "_links": { "_self": "string", "results": [ { "delivery": "pending", "name": "string", "location": "string", "expires_at": "2019-08-24T14:15:22Z" } ] }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "tools": [ { "target_sensor": null } ], "metadata": { "stac": { } }, "products": [ { "item_ids": [ "string" ], "item_type": "string", "product_bundle": "string" } ], "created_on": "string", "last_modified": "string", "state": "queued", "last_message": "string", "error_hints": [ "string" ], "delivery": { "single_archive": true, "archive_type": "string", "archive_filename": "string", "layout": { "format": "standard" }, "amazon_s3": { "bucket": "string", "aws_region": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string", "path_prefix": "string" }, "azure_blob_storage": { "account": "string", "container": "string", "sas_token": "string", "storage_endpoint_suffix": "string", "path_prefix": "string" }, "google_cloud_storage": { "bucket": "string", "credentials": "string", "path_prefix": "string" }, "google_earth_engine": { "project": "string", "collection": "string", "credentials": "string" }, "oracle_cloud_storage": { "bucket": "string", "customer_access_key_id": "string", "customer_secret_key": "string", "region": "string", "namespace": "string", "path_prefix": "string" }, "planet_folders": { "folder_id": "string" }, "s3_compatible": { "bucket": "string", "endpoint": "string", "region": "string", "access_key_id": "string", "secret_access_key": "string", "path_prefix": "string", "use_path_style": false }, "destination": { "ref": "string", "path_prefix": "string" } }, "notifications": { "webhook": { "url": "string", "per_order": true }, "email": true }, "order_type": "partial", "source_type": "scenes", "hosting": { "sentinel_hub": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "create_configuration": true, "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684" } } } ] }` ## [](#tag/Orders/operation/createOrder)Create Order Orders products. ##### Authorizations: *BasicAuth**ApiKeyAuth* ##### header Parameters | | | | ------------ | --------------------------------------------- | | X-Planet-App | stringIdentify the client making this request | ##### Request Body schema: application/jsonrequired Order details. | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | namerequired | stringA name given to this Order request. | | products | Array of scenesSource (object) or basemapsSource (object)The products from the Data or Basemaps API to order. | | delivery | object (Delivery)How should ordered products be delivered? | | notifications | object (Notifications)How would you like to be notified when order is complete? | | order\_type | stringDefault: "full"Enum: "partial" "full"accept order if requested products are not available (partial)? | | source\_type | stringDefault: "scenes"Enum: "scenes" "basemaps"Source imagery type for all products. Default is scenes. | | tools | Array of harmonizeObject (object) or coregisterObject (object) or toarObject (object) or clipObject (object) or reprojectObject (object) or bandmathObject (object) or compositeObject (object) or tileObject (object) or cloud\_filterObject (object) or file\_formatObject (object) or mergeObject (object) or clipBasemapsObject (object) or file\_formatBasemapsObject (object) | | metadata | object (Metadata)Metadata settings | | hosting | object (Hosting)Specify a data hosting location. A hosting location removes the need to specify a delivery location. Specifying both is not allowed. If hosting is specified, no direct download links will be generated. This location cannot be updated after an order has been created. | ### Responses **202** The Order Request was accepted, and is processing. **400** Invalid request. **401** Access denied - insufficient privileges. **403** The request was authenticated but refused by the server. The response `code` field identifies the specific reason for the refusal, and the `message` field provides a human-readable explanation suitable for display to the user. **409** Order concurrency limit reached. **500** Server Error. **default** Other error. post/orders/v2 https\://api.planet.com/compute/ops/orders/v2 ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "name": "string", "products": [ { "item_ids": [ "string" ], "item_type": "string", "product_bundle": "string" } ], "delivery": { "single_archive": true, "archive_type": "string", "archive_filename": "string", "layout": { "format": "standard" }, "amazon_s3": { "bucket": "string", "aws_region": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string", "path_prefix": "string" }, "azure_blob_storage": { "account": "string", "container": "string", "sas_token": "string", "storage_endpoint_suffix": "string", "path_prefix": "string" }, "google_cloud_storage": { "bucket": "string", "credentials": "string", "path_prefix": "string" }, "google_earth_engine": { "project": "string", "collection": "string", "credentials": "string" }, "oracle_cloud_storage": { "bucket": "string", "customer_access_key_id": "string", "customer_secret_key": "string", "region": "string", "namespace": "string", "path_prefix": "string" }, "planet_folders": { "folder_id": "string" }, "s3_compatible": { "bucket": "string", "endpoint": "string", "region": "string", "access_key_id": "string", "secret_access_key": "string", "path_prefix": "string", "use_path_style": false }, "destination": { "ref": "string", "path_prefix": "string" } }, "notifications": { "webhook": { "url": "string", "per_order": true }, "email": true }, "order_type": "partial", "source_type": "scenes", "tools": [ { "target_sensor": null } ], "metadata": { "stac": { } }, "hosting": { "sentinel_hub": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "create_configuration": true, "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684" } } }` ### Response samples * 202 * 400 * 401 * 403 * 409 * 500 * default Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "results": [ { "delivery": "pending", "name": "string", "location": "string", "expires_at": "2019-08-24T14:15:22Z" } ] }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "tools": [ { "target_sensor": null } ], "metadata": { "stac": { } }, "products": [ { "item_ids": [ "string" ], "item_type": "string", "product_bundle": "string" } ], "created_on": "string", "last_modified": "string", "state": "queued", "last_message": "string", "error_hints": [ "string" ], "delivery": { "single_archive": true, "archive_type": "string", "archive_filename": "string", "layout": { "format": "standard" }, "amazon_s3": { "bucket": "string", "aws_region": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string", "path_prefix": "string" }, "azure_blob_storage": { "account": "string", "container": "string", "sas_token": "string", "storage_endpoint_suffix": "string", "path_prefix": "string" }, "google_cloud_storage": { "bucket": "string", "credentials": "string", "path_prefix": "string" }, "google_earth_engine": { "project": "string", "collection": "string", "credentials": "string" }, "oracle_cloud_storage": { "bucket": "string", "customer_access_key_id": "string", "customer_secret_key": "string", "region": "string", "namespace": "string", "path_prefix": "string" }, "planet_folders": { "folder_id": "string" }, "s3_compatible": { "bucket": "string", "endpoint": "string", "region": "string", "access_key_id": "string", "secret_access_key": "string", "path_prefix": "string", "use_path_style": false }, "destination": { "ref": "string", "path_prefix": "string" } }, "notifications": { "webhook": { "url": "string", "per_order": true }, "email": true }, "order_type": "partial", "source_type": "scenes", "hosting": { "sentinel_hub": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "create_configuration": true, "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684" } } }` ## [](#tag/Orders/operation/getOrder)Get Order Get order request details by Id. ##### Authorizations: *BasicAuth**ApiKeyAuth* ##### path Parameters | | | | ----------------- | ------------------------------------ | | order\_idrequired | string \The Order ID (a UUID). | ### Responses **200** Gets a single Order record. **401** Access denied - insufficient privileges. **404** Item not found. **500** Server Error. **default** Other error. get/orders/v2/{order\_id} https\://api.planet.com/compute/ops/orders/v2/{order\_id} ### Response samples * 200 * 401 * 404 * 500 * default Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "results": [ { "delivery": "pending", "name": "string", "location": "string", "expires_at": "2019-08-24T14:15:22Z" } ] }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "tools": [ { "target_sensor": null } ], "metadata": { "stac": { } }, "products": [ { "item_ids": [ "string" ], "item_type": "string", "product_bundle": "string" } ], "created_on": "string", "last_modified": "string", "state": "queued", "last_message": "string", "error_hints": [ "string" ], "delivery": { "single_archive": true, "archive_type": "string", "archive_filename": "string", "layout": { "format": "standard" }, "amazon_s3": { "bucket": "string", "aws_region": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string", "path_prefix": "string" }, "azure_blob_storage": { "account": "string", "container": "string", "sas_token": "string", "storage_endpoint_suffix": "string", "path_prefix": "string" }, "google_cloud_storage": { "bucket": "string", "credentials": "string", "path_prefix": "string" }, "google_earth_engine": { "project": "string", "collection": "string", "credentials": "string" }, "oracle_cloud_storage": { "bucket": "string", "customer_access_key_id": "string", "customer_secret_key": "string", "region": "string", "namespace": "string", "path_prefix": "string" }, "planet_folders": { "folder_id": "string" }, "s3_compatible": { "bucket": "string", "endpoint": "string", "region": "string", "access_key_id": "string", "secret_access_key": "string", "path_prefix": "string", "use_path_style": false }, "destination": { "ref": "string", "path_prefix": "string" } }, "notifications": { "webhook": { "url": "string", "per_order": true }, "email": true }, "order_type": "partial", "source_type": "scenes", "hosting": { "sentinel_hub": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "create_configuration": true, "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684" } } }` ## [](#tag/Orders/operation/cancelOrder)Cancel an order Cancel a queued order by Id. ##### Authorizations: *BasicAuth**ApiKeyAuth* ##### path Parameters | | | | ----------------- | ------------------------------------ | | order\_idrequired | string \The Order ID (a UUID). | ### Responses **200** Returns the cancelled order details. **401** Access denied - insufficient privileges. **404** Item not found. **409** Order is not in a cancellable state. **500** Server Error. **default** Other error. put/orders/v2/{order\_id} https\://api.planet.com/compute/ops/orders/v2/{order\_id} ### Response samples * 200 * 401 * 404 * 409 * 500 * default Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "results": [ { "delivery": "pending", "name": "string", "location": "string", "expires_at": "2019-08-24T14:15:22Z" } ] }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "tools": [ { "target_sensor": null } ], "metadata": { "stac": { } }, "products": [ { "item_ids": [ "string" ], "item_type": "string", "product_bundle": "string" } ], "created_on": "string", "last_modified": "string", "state": "queued", "last_message": "string", "error_hints": [ "string" ], "delivery": { "single_archive": true, "archive_type": "string", "archive_filename": "string", "layout": { "format": "standard" }, "amazon_s3": { "bucket": "string", "aws_region": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string", "path_prefix": "string" }, "azure_blob_storage": { "account": "string", "container": "string", "sas_token": "string", "storage_endpoint_suffix": "string", "path_prefix": "string" }, "google_cloud_storage": { "bucket": "string", "credentials": "string", "path_prefix": "string" }, "google_earth_engine": { "project": "string", "collection": "string", "credentials": "string" }, "oracle_cloud_storage": { "bucket": "string", "customer_access_key_id": "string", "customer_secret_key": "string", "region": "string", "namespace": "string", "path_prefix": "string" }, "planet_folders": { "folder_id": "string" }, "s3_compatible": { "bucket": "string", "endpoint": "string", "region": "string", "access_key_id": "string", "secret_access_key": "string", "path_prefix": "string", "use_path_style": false }, "destination": { "ref": "string", "path_prefix": "string" } }, "notifications": { "webhook": { "url": "string", "per_order": true }, "email": true }, "order_type": "partial", "source_type": "scenes", "hosting": { "sentinel_hub": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "create_configuration": true, "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684" } } }` ## [](#tag/Orders/operation/bulkCancelOrders)Cancel Orders in bulk Cancel Orders in bulk ##### Authorizations: *BasicAuth**ApiKeyAuth* ##### Request Body schema: application/jsonrequired Bulk cancel details; empty body attempts to cancel all Orders in a pre-running state. | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | order\_ids | Array of strings \ (OrderID) \[ 1 .. 10000 ] items \[ items \ ]Optional array of Order IDs to attempt to cancel | ### Responses **200** Cancel succeeded for some of the specified Orders **401** Access denied - insufficient privileges. **404** Item not found. **500** Server Error. **default** Other error. post/bulk/orders/v2/cancel https\://api.planet.com/compute/ops/bulk/orders/v2/cancel ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "order_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 200 * 401 * 404 * 500 * default Content type application/json Copy Expand all Collapse all `{ "result": { "succeeded": { "count": 0 }, "failed": { "count": 0, "failures": [ { "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe", "message": "string" } ] } } }` ## [](#tag/Orders/operation/stats)Aggregated Order Stats Provides aggregated counts of Active Orders for the User and the User's Organization. ##### Authorizations: *BasicAuth**ApiKeyAuth* ### Responses **200** Returns the aggregated stats. **401** Access denied - insufficient privileges. **500** Server Error. **default** Other error. get/stats/orders/v2 https\://api.planet.com/compute/ops/stats/orders/v2 ### Response samples * 200 * 401 * 500 * default Content type application/json Copy Expand all Collapse all `{ "user": { "queued_orders": 0, "running_orders": 0 }, "organization": { "queued_orders": 0, "running_orders": 0 } }` ## [](#tag/Orders/operation/downloadOrder)Download Order Download ordered asset. ##### query Parameters | | | | ------------- | --------------------- | | tokenrequired | stringDownload token. | ##### header Parameters | | | | ------------ | --------------------------------------------- | | X-Planet-App | stringIdentify the client making this request | ### Responses **302** redirect to cloud provider for actual download. **401** Access denied - insufficient privileges. **404** Item not found. **500** Server Error. **default** Other error. get/download https\://api.planet.com/compute/ops/download ### Response samples * 401 * 404 * 500 * default Content type application/json Copy `{ "message": "string" }` ## [](#tag/Orders/operation/getSpec)Get OpenAPI spec Returns this OpenAPI spec ### Responses **200** The spec as a JSON object **500** Server Error. get/spec https\://api.planet.com/compute/ops/spec ### Response samples * 200 * 500 Content type application/json Copy `{ }` ## [](#tag/Orders/operation/getBundlesSpec)Get json spec for product bundles Returns the json spec for product bundles ### Responses **200** The bundles spec as a JSON object **500** Server Error. get/bundles/spec https\://api.planet.com/compute/ops/bundles/spec ### Response samples * 200 * 500 Content type application/json Copy `{ }` ## [](#tag/Orders/operation/getCompatibilitySpec)Get compatibility specification for item types, bundles, and tools Returns the compatibility specification showing which bundles are available for each item type and which tools are compatible ##### query Parameters | | | | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | by | stringEnum: "item-types" "item\_types" "tools"Filter the response to show only specific views. Valid values are 'item-types' (or 'item\_types') to show only item types view, 'tools' to show only tools view, or omit to show both views (default). | ### Responses **200** The compatibility spec as a JSON object **500** Server Error. get/compatibility/spec https\://api.planet.com/compute/ops/compatibility/spec ### Response samples * 200 * 500 Content type application/json Copy `{ }`