Skip to main content

Subscriptions Overview

The Subscriptions API provides continuous cloud delivery of imagery and Planetary Variables. The Subscriptions API is Planet's recommended data delivery API for customers in need of continuous data feed over areas of interest. With the Planet Subscriptions API, you can subscribe to imagery and Planetary Variables, allowing you to create, monitor, and access these products through the Subscriptions API.

Delivery through the Subscriptions API allows for automation, seamless integration, scalability, customization, and consistent access to the data, while reducing the data processing burden on your end. With Subscriptions API, you can tailor the data request parameters to suit your needs, such as defining the area of interest, time range, and data frequency. This flexibility ensures you receive the most relevant data for your use case.

To create a subscription, you can specify the filter, applicable tools, and a cloud delivery location. The API automatically processes and delivers all items which meet your subscription criteria, as soon as they are published to the catalog.

Subscriptions API Components​

Service Contract​

A subscription request has four main blocks.

  • source: Describes the data products and criteria defining the subscription's delivery. For catalog imagery (For example, PlanetScope, SkySat), the catalog source type is supported. It takes item_types, asset_types, geometry, start_time, and a filter, and closely mirrors a Data API /quick-search request. For Planetary Variables and Analysis-Ready PlanetScope, the source type is based on the product offering: biomass_proxy, land_surface_temperature, soil_water_content, vegetation_optical_depth, field_boundaries_sentinel_2_p1m, forest_carbon_diligence_30m, analysis_ready_ps.
  • tools: Describes raster tools that may be applied to an imagery subscription. For Planetary Variables, all rasters are clipped to the subscription’s AOI, and no additional tools are supported.
  • delivery: Describes the delivery details for the Google Cloud Storage, Amazon S3, Microsoft Azure or Oracle Cloud Storage for the items returned by the subscription.
  • hosting: Describes the Sentinel Hub collection location for the items returned by the subscription.
  • notifications: Describes the notifications which can be delivered for a subscription.

States & Status Descriptions​

The flowchart below shows the possible subscription statuses. The status of a subscription can be found in the status value of an API response.

StatusDescription
preparingThe subscription was successfully submitted and is being set up.
pendingThe subscription’s start time has not yet passed or data is being generated; delivery has not yet started.
runningThe subscription’s start time has passed and it is actively monitoring for new data; delivery may be in progress.
completedAll expected items have been delivered. If a subscription has ended recently, there will be a brief delay before it is completed. The delay is typically 7 days, but may differ based on the source type. Items may be delivered within a 60-day grace period after the subscription was marked as completed. After the grace period, delivery has stopped.
cancelledThe subscription was cancelled by a user; delivery has stopped.
suspendedThe subscription has a policy or quota conflict; delivery has stopped.
failedThere was an issue with the subscription.

Forwardfill & Backfill Subscriptions​

The Subscriptions API supports delivery of both archive imagery and future imagery collections.

  • Forwardfill subscriptions are subscriptions with an end time in the future.
  • Backfill subscriptions are subscriptions with a start and end time in the past.

Subscriptions may have either a backfill or forwardfill portion, or both. For example, a subscription’s start time may be 3 years in the past to gather baseline data and then end at a time in the future. As long as a forwardfill subscription is running, you can update it.

During periods of high demand, Planet load balances data production and delivery between customers and their individual subscriptions to deliver a steady stream of data as quickly as possible. For each subscription, delivery of forwardfill data is prioritized over backfill so that customers always have access to the latest data as soon as possible.

The Planet SDK for Python also supports connecting to the Subscriptions API and has a powerful “backfill” capability to bulk order historical imagery to your area of interest.

API Limits​

info

These limits are validated when a subscription is created. If an organization exceeds its limits, all existing active subscriptions (For example, end_time has not passed) continue to deliver imagery and are not suspended or cancelled. Only new subscriptions cannot be created.

Additionally, new subscriptions cannot be created if an organization has insufficient quota. However, active systems are not suspended or canceled.

An “active” subscription is one where the end_time has not passed.

Subscriptions API use is limited to a maximum count of active subscriptions and a maximum total count of expected items delivered daily across all forwardfill portions of subscriptions.

Previously, backfill was limited to 5 years before start_time. As of 2025, this limitation has been removed.

  • Max Forwardfill Subscriptions: Maximum number of active subscriptions. A new subscription may not be created if an organization has already maxed out its active subscriptions.

  • Total Expected Forwardfill Items Delivered Daily: Total number of expected items matched and delivered daily across all forwardfill subscriptions. A new forwardfill subscription cannot be created if its expected number of items delivered daily puts the organization over its total cap.

    • To estimate the expected number of items a forwardfill subscription will deliver daily, the Subscriptions API uses Data API’s Search Stats endpoint. It averages daily items matched over the last seven days. These numbers are totaled across all forwardfill subscriptions.

    • Note: The "expected items delivered daily" field is validated upfront at subscription creation. The Subscriptions API does not artificially limit item delivery if a subscription matches more items than expected on a given day.

      By default, customers are subject to the following limits:

Max Subscriptions: 2,000 Total Expected Forwardfill Items Delivered Daily: 2,000 Please contact your Account Manager, or submit a request, if you need these limits to be increased.

Rate Limits​

To improve the experience for all of our users, Planet uses rate limiting to prevent overloading the system. If handled correctly, rate limiting errors can be a normal and useful part of working with the API.

The Planet API responds with an HTTP 429 response code when a rate limit has been exceeded. When this occurs, we recommend implementing retry with an exponential backoff. An exponential backoff means that waiting for exponentially longer intervals between each retry of a single failing request.

The following rate limits are currently in place:

  • Subscription Creation - 5 requests per second, per API key.
  • Subscription Cancelation - 5 requests per second, per API key.
  • Get Subscription - 5 requests per second, per API key.
  • Get Subscription Results - 5 requests per second, per API key.

Errors​

Request Failed Schema Validation​

HTTP status code: 400

This may return, but is not limited to:

{
  "error": {
    "reason": "Request failed schema validation",
    "details": []
  }
}

It is crucial to adhere to the expected request body structure as defined in the API reference. Errors in the request body can lead to a schema validation error. Some examples of errors that may trigger schema validation errors, include, but are not limited to:

Syntax errors​

  • Mismatched Parentheses or Brackets: Ensure that all opening brackets ({, [) have corresponding closing brackets (}, ]) and that they are nested correctly.
  • Missing Commas: Ensure that commas separate elements in arrays and properties in objects.

Spelling mistakes​

  • Incorrect Property Names: Ensure that property names are spelled correctly per the API documentation.

Data format errors​

  • Incorrect Date Format: Dates should be formatted as per the ISO 8601 standard, i.e. YYYY-MM-DDTHH:MM:SSZ. For example, 2021-03-01T00:00:00Z is a valid date, whereas 2021/03/01 00:00:00 is not.
  • Invalid Data Types: Ensure that the data types for each property match the expected data types per the API documentation. For instance, if a property expects a string, it should not receive an int or an array.

Bad Requests​

HTTP status code: 400

This may return a number of errors, including but not limited to:

{
  "error": {
    "reason": "Problem with request",
    "details": []
  }
}

This error is a general indication that there was an issue with the setup or structure of your API request. Here are some potential causes and how to avoid them:

Invalid cloud delivery settings​

  • Invalid Credentials: Ensure that the credentials provided in the cloud delivery settings are accurate and have the necessary permissions. Incorrect credentials can prevent the API from authenticating and processing your request successfully.
  • Incorrect Delivery Destination: Verify that the cloud delivery settings (For example, bucket) are correctly configured. An incorrect setup can lead to failures.

Request structure and data issues​

  • Incomplete Request Body: Ensure that the request body is complete and includes all the necessary parameters. Missing parameters can cause the request to fail.
  • Tools are used in an appropriate way: For example, bandmath supports the pixel types ‘8U, 16U, 16S, 32R, and auto’ and may trigger this error if the pixel type input is incorrect.
  • Planetary Variables:

Invalid asset type (scene subscriptions)​

The request will fail if the asset_types field contains an unsupported or non-existent asset type. For instance, specifying an asset type that doesn't match asset types available in the satellite imagery database. You should verify that the asset types specified in the request (like ortho_analytic_4b) are valid and supported by the API.

Incorrect item type (scene subscriptions)​

  • Similar to the asset type, specifying an incorrect item type in the item_types field can cause a problem. You should ensure that the item types specified (like PSScene) are valid and supported by the API.
  • Start Time After End Time: If the start_time is specified to be a time after the end_time, it will be rejected.
  • Unsupported Recurrence Rules: If the subscription source supports recurrence rules and you specify a rule that is not supported or is syntactically incorrect, it can cause an error.
  • Invalid Geometry Coordinates: Specifying a geometry with coordinates that is not valid GeoJSON can be another source problem. This might include coordinates that do not close to form a loop or coordinates that cross over each other, forming an invalid shape.

Feasibility issues​

When you submit a creation request over an area where Planetary Variable or Analysis-Ready Planetscope data may not be available, you will receive an infeasible area error message indicating that the product unavailable in the subscription geometry you provided. Please update your subscription geometry to be within a feasible area and try again.

Unauthenticated​

HTTP status code: 401

This error may be displayed when the system can’t verify the validity of the user.

API key​

Requests may be rejected when the API key entered is invalid. This may return:

API key not found

Unauthorized​

HTTP status code: 403

This error may be displayed when the user does not have permission to access the requested resource.

  • Requested product(s) or geographies are not provisioned for the user.
  • User is not authorized to take the requested action.

Internal Server Error​

HTTP status code: 500

Something went wrong while the server was processing the request.

This may return, but is not limited to:

{
  "error": {
    "reason": "Unexpected error",
    "details": []
  }
}

An internal error was experienced while processing the request. Try again later, and contact support if it persists.

📖

Get Started with Planet APIs

Find more APIs and learn how to start using them.

🎓

Planet University

Explore video tutorials on how to order data with Planet APIs

📓

Subscriptions Jupyter Notebooks

Check out the Jupyter notebooks tutorial on GitHub for using the Subscriptions API.

Last updated on