Skip to main content
View as Markdown

Quota Reservations API

Overview​

Planet Quota Reservations API allows you to create, estimate, and view existing quota reservations on the Planet platform for compatible products including Planetary Variables, Analysis-Ready PlanetScope (ARPS), and select PlanetScope imagery products.

Using feature references created in Features API you can reserve quota, estimate quota usage, or view how much your currently reserved features have consumed.

Prerequisites​

Before using the Quota API, ensure you have:

  • A Planet API key (learn how to get one)
  • Created Areas of Interest (AOIs) using the Features API
  • Access to quota-enabled products in your organization's subscription
note

The Quota API does not have rate limits. For general rate limiting information, see the rate limiting page.

Key Concepts​

AOI Reference​

A unique identifier returned by the Features API when you upload an Area of Interest (AOI). This reference follows the format pl:features/{dataset}/{collection-id}/{feature-id}. See Feature References for more details on how to obtain and use these references.

Product​

A data product you are authorized to access along with a record of your reserved quota and remaining quota.

The Quota API supports reservation for the following categories of data products:

tip

To see the exact products available to your organization with quota reservation support, check the supports_reservation: true field in the /my/products API response. Product availability depends on your organization's subscriptions and entitlements.

Quota Reservation​

The outcome of POSTing one or more AOI references and valid product ID to Quota API

Quota Limits​

  • Quota Total: The maximum amount of quota available for your organization to reserve
  • Quota Used: The amount of quota already consumed through existing reservations
  • Quota Remaining: The difference between total and used quota (calculated as quota_total - quota_used)

Collection​

An optional grouping mechanism for organizing related quota reservations. This is distinct from Feature Collections in the Features API. Quota collections help you:

  • Track reservations for a specific project or campaign
  • Generate aggregated reports across multiple reservations
  • Manage quota allocations by business unit or use case

Job​

An asynchronous processing task created when you submit bulk reservation requests. Jobs allow you to:

  • Reserve quota for multiple AOIs in a single request
  • Track the progress of large reservation operations that may take minutes to hours
  • Monitor the status of your bulk operations via the /jobs endpoints

Getting Started​

Quota Reservation Workflow​

The typical workflow for reserving quota follows these steps:

  1. Upload your AOI to the Features API and obtain a feature reference
  2. Check available products using /my/products to find quota-enabled products
  3. Estimate quota usage (optional) using /estimate to preview consumption
  4. Create reservation using /reservations with your AOI reference and product ID
  5. Monitor consumption by viewing reservation details and tracking usage

Check Available Products​

First, verify which products support quota reservations in your organization:

curl -X GET "https://api.planet.com/account/v1/my/products" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Look for products with "supports_reservation": true in the response. This endpoint also shows your current quota status for each product.

Estimate Quota Usage​

Before creating a reservation, you can estimate how much quota will be consumed:

curl -X POST "https://api.planet.com/account/v1/quota-reservations/estimate" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": [ "pl:features/my/collection-id/feature-id" ],
        "product_id": 123
    }'

Common Operations​

Creating an Area Quota Reservation​

Get Your Products​

You complete area quota requests within the context of a product. To create or estimate a quota reservation, first retrieve a valid id from my/products that displays the products currently available to your organization.

The /my/products endpoint returns a subset of all products you can access, and includes all products that support quota reservations. Each product in the response includes:

  • id: The unique identifier of how this product is assigned to you, to use as product_id in reservation requests
  • name: The product identifier, independent of assignment (e.g., "FCM_30M")
  • title: Human-readable product name
  • description: Product description
  • supports_reservation: Boolean indicating if the product supports quota reservations (only products with true can be used with reservation endpoints)
  • quota_total: Total quota available for your organization
  • quota_used: Quota already consumed or reserved
  • unlimited_quota: Whether the product has unlimited quota
Where to check your remaining quota

Check your remaining quota in one of these places:

  • For products that support reservations and some others: Use /my/products (shown above) and calculate quota_total - quota_used
  • If your product isn't listed: Check /my/subscriptions instead
Migration Note

The quota reservation API parameter has been standardized to product_id. If you have existing integrations using product_access_id, please update them to use product_id instead. Both parameters accept the same integer values (the product ID from the /my/products response). The product_access_id parameter is deprecated but temporarily supported for backward compatibility.

curl -X GET "https://api.planet.com/account/v1/my/products" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Estimate Quota Cost​

To estimate a quota reservation, upload your Areas of Interest (AOIs) using the Planet Features API. Use the generated feature reference as your aoi_refs value.

Use the ID value fetched from Get Your Products as your product_id parameter.

curl -X POST "https://api.planet.com/account/v1/quota-reservations/estimate" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": [ "pl:features/my/collection-id/feature-id" ],
        "product_id": 123
    }'

Make a Reservation​

Making a reservation follows the same pattern as estimating. Retrieve one or more valid aoi_refs and product_id to complete a request.

info

To reserve a large list of aoi_refs, please refer to the section on bulk requests

curl -X POST "https://api.planet.com/account/v1/quota-reservations/" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": [ "$AOI_REF" ],
        "product_id": $PRODUCT_ID
    }'

View Your Quota Reservations​

To view the status of your created quota reservations, run:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/" \
    --include \
    -H "Authorization api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

View a Specific Quota Reservation​

To view a specific quota reservation, run:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/100" \
    --include \
    -H "Authorization api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Bulk Requests​

Making Bulk Reservations​

Follow the same instructions for making a reservation, and include as many aoi_refs as you need to reserve. If you want to reserve all features within a feature collection you can supply the aoi_ref of the collection instead of each individual feature reference. "aoi_refs":["pl:features/my/collection-id"]

For best performance, POST one payload containing all of your aoi_refs rather than chunking and making multiple requests.

When you use the bulk reservation endpoint (/bulk-reserve), your request processes asynchronously. The API returns a job ID that you can use to track the progress of your bulk reservation.

info

There is a 10 megabyte request body limit to remember when submitting large bulk reservations.

curl -X POST "https://api.planet.com/account/v1/quota-reservations/bulk-reserve" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "aoi_refs": $AOI_REF_ARRAY,
        "product_id": $PRODUCT_ID
    }'

Tracking Bulk Reservation Progress​

After you submit a bulk reservation request, monitor its progress using the job ID returned in the response.

To check the status of a specific job:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/jobs/{job_id}" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

To list all jobs for your organization:

curl -X GET "https://api.planet.com/account/v1/quota-reservations/jobs" \
    --include \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"
note

Bulk reservations are processed asynchronously and may take minutes to hours to complete depending on the number of AOI references and their complexity. Job status values include:

  • pending: Job is queued for processing
  • processing: Job is actively being processed
  • completed: Job finished successfully
  • failed: Job encountered an error

API Mechanics​

Pagination​

The Quota API paginates responses to limit results, making them easier to work with.

Your first GET request yields the first page with a meta object containing next values representing the location of the next page. Following the next link returns another page of results. The prev link returns the previous set of results. The meta object also contains a count representing the number of records in your request.

These API methods share a common structure and accept, at a minimum, the following parameters: limit and offset. Quota API GET methods use offset-based pagination through the offset parameter.

Error Handling​

The API returns an error object whenever an error occurs, whether due to user input or an internal system issue.

HTTP response codes of 4xx suggest a bad request. If you receive a 4xx response, review the API reference docs for more context to help you troubleshoot. 5xx errors suggest a problem on Planet's end, so if you receive a 5xx error, please contact support.

Last updated on