Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/quota/) # 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](https://docs.planet.com/develop/apis/features.md) 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](https://docs.planet.com/develop/authentication.md#obtaining-your-api-key)) * Created Areas of Interest (AOIs) using the [Features API](https://docs.planet.com/develop/apis/features.md) * 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](https://docs.planet.com/develop/rate-limiting.md) page. ## Key Concepts ### AOI Reference A unique identifier returned by the [Features API](https://docs.planet.com/develop/apis/features.md) when you upload an Area of Interest (AOI). This reference follows the format `pl:features/{dataset}/{collection-id}/{feature-id}`. See [Feature References](https://docs.planet.com/develop/apis/features.md#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: * **[Planetary Variables](https://docs.planet.com/data/planetary-variables.md)** - Advanced analytics products for agriculture, forestry, and environmental monitoring * **[Analysis-Ready PlanetScope (ARPS)](https://docs.planet.com/data/imagery/arps.md)** - Pre-processed surface reflectance data prepared for analysis * **[PlanetScope](https://docs.planet.com/data/imagery/planetscope.md)** - Select PlanetScope monitoring and access 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](https://docs.planet.com/develop/apis/features.md#key-concepts) 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 ``` 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 ``` 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 ``` 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](https://docs.planet.com/develop/apis/features.md). 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 ``` 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](#bulk-requests) * CURL ``` 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 ``` 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 ``` 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 ``` 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 ``` 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 ``` 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](https://docs.planet.com/develop/apis/quota/reference.md) 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](https://support.planet.com/).