--- updatedAt: 2025-09-23T16:26:01.000Z agentTools: projectIndex: https://docs.canopy.umbra.space/llms.txt --- # Task Lifecycle Tutorial This tutorial provides a step‑by‑step guide on how to schedule a Task and retrieve its delivered data from start to finish via API or UI # API Users ## Send Feasibility Request Send a cURL request as follows, inserting your Bearer Token, latitude, longitude, and tasking window in ISO8601 format (YYYY-MM-DDT00:00:00Z), as well as modifying any other parameters desired. ```curl curl --request POST \ --url https://api.canopy.umbra.space/tasking/feasibilities \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data '{ "imagingMode": "SPOTLIGHT", "spotlightConstraints": { "geometry": { "type": "Point", "coordinates": [ , ] }, "polarization": "VV", "rangeResolutionMinMeters": 1, "multilookFactor": 1, "grazingAngleMinDegrees": 30, "grazingAngleMaxDegrees": 70, "targetAzimuthAngleStartDegrees": 0, "targetAzimuthAngleEndDegrees": 360 }, "windowStartAt": "", "windowEndAt": "" }' ``` This will return a Feasibility ID, which can be used to poll for Opportunities. ## Poll for Opportunities Insert your Bearer Token and Feasibility ID to poll for opportunities. When status transitions to COMPLETED, Opportunities list will be populated with Opportunities. If opportunities is null, resubmit step 1 with a longer time window. ```curl curl --request GET \ --url https://api.canopy.umbra.space/tasking/feasibilities/ \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` An example of a successful opportunity looks as follows: ```json { "durationSec": 106.0, "grazingAngleEndDegrees": 41.62010781558027, "grazingAngleStartDegrees": 41.62947469239037, "groundRangeEndKm": 526.66330627147, "groundRangeStartKm": 525.8848195176256, "slantRangeEndKm": 764.1847054671697, "slantRangeStartKm": 761.6243772652538, "squintAngleEndDegrees": 135.31102583657602, "squintAngleStartDegrees": 45.11766881409077, "targetAzimuthAngleEndDegrees": 305.63160791809025, "targetAzimuthAngleStartDegrees": 214.67019647500493, "windowEndAt": "2023-02-11T21:58:07.682855+00:00", "windowStartAt": "2023-02-11T21:56:21.682855+00:00" } ``` ## Create a Task using an Opportunity To create a new Task Request that captures a specific Opportunity, copy the entire spotlightConstraints object from your Feasibility Request into the Task Request. Then copy the windowStartAt and windowEndAt from the Opportunity you'd like to use into the Task Request. ```curl curl --request POST \ --url https://api.canopy.umbra.space/tasking/tasks \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data '{ "imagingMode": "SPOTLIGHT", "spotlightConstraints": , "windowStartAt": "", "windowEndAt": "", "taskName": "" }' ``` This will return JSON containing a Task ID, which can be used to poll Task status updates. ## Poll for Task by ID Use the Task\_ID from the previous request to poll for status updates: ```curl curl --request GET \ --url https://api.canopy.umbra.space/tasking/tasks/ \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` Tasks should transition to "SCHEDULED" status once they have been added to the schedule. When a Task status transitions to "DELIVERED" data from the collect is ready to be downloaded via the STAC endpoints. You will need your Task\_id to complete the following step. ## Retrieve Associated Collect IDs from Task Your collect data can be downloaded once the collect status is "DELIVERED". This will generally happen 1-4 hours after the associated Task's windowEndAt has passed. In order to do that, you need to first get your Collect\_id. To do so, use the following cURL request: ```curl curl --request GET \ --url https://api.canopy.umbra.space/tasking/tasks/ \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` The response will contain a `collectIds` property with the Collect IDs assocated with this Task. ## Retrieve Item for data download link Use the following cURL request to retrieve the link to your data, inserting your Organization ID, the Collect ID from the previous step, and your Bearer Token. Your Organization ID can be retrieved by logging into Canopy and navigating to your [account settings](https://canopy.umbra.space/account) ```curl curl --request GET \ --url https://api.canopy.umbra.space/stac/collections//items/ \ --header 'accept: application/json' \ --header 'authorization: Bearer ' ``` The STAC Item response will include pre-signed urls that allow direct download of your data. The STAC Item conforms to the [Alternate Assets](https://github.com/stac-extensions/alternate-assets) extension using the object key `s3_signed`. See below for an example response: ```json { "id": "c345090b-b20a-4d45-9ea6-2691ccefc12e", "assets": { "2023-02-21-16-12-39_UMBRA-04.tif": { "href": "s3://...", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "created": "2023-02-21T17:59:28Z", "description": "GEC", "alternate": { "s3_signed": { "title": "S3 signed url for direct download", "description": "Expires at: 2023-02-22T00:06:15+00:00", "href": "https://..." } } }, "2023-02-21-16-12-39_UMBRA-04.cphd": { "href": "s3://...", "type": "application/octet-stream", "created": "2023-02-21T17:59:28Z", "description": "CPHD", "alternate": { "s3_signed": { "title": "S3 signed url for direct download", "description": "Expires at: 2023-02-22T00:06:15+00:00", "href": "https://..." } } }, "2023-02-21-16-12-39_UMBRA-04_SICD.nitf": { "href": "s3://...", "type": "application/octet-stream", "created": "2023-02-21T17:59:27Z", "description": "SICD", "alternate": { "s3_signed": { "title": "S3 signed url for direct download", "description": "Expires at: 2023-02-22T00:06:15+00:00", "href": "https://..." } } }, "2023-02-21-16-12-39_UMBRA-04_SIDD.nitf": { "href": "s3://...", "type": "application/octet-stream", "created": "2023-02-21T17:59:28Z", "description": "SIDD", "alternate": { "s3_signed": { "title": "S3 signed url for direct download", "description": "Expires at: 2023-02-22T00:06:15+00:00", "href": "https://..." } } }, "2023-02-21-16-12-39_UMBRA-04_METADATA.json": { "href": "s3://...", "type": "application/json", "created": "2023-02-21T17:59:28Z", "description": "METADATA", "alternate": { "s3_signed": { "title": "S3 signed url for direct download", "description": "Expires at: 2023-02-22T00:06:15+00:00", "href": "https://..." } } } }, "links": [...], "geometry": {...}, "collection": "...", "properties": {...} } ``` # UI Users Canopy makes it easy to submit new tasking requests. In this example we'll be tasking using Spotlight imaging mode. Spotlight tasking accepts a point target and produces a 5x5 km scene of guaranteed resolution centered on the target input. The orientation of the footprint will depend on the orbit of the satellite. To start a new tasking request, click the Schedule a Task button on the left sidebar from anywhere in the application. 1. **Set a target location** Set the point target coordinates (Lng, Lat) in the Location field from the left control panel. Alternatively, the location field can be populated by clicking anywhere on the map, or by searching for a location name in the field 2. **Set the tasking window** The tasking window input defines the desired start and end range of the time of acquisition. Feasibility results for the task will be constrained to the range provided. The end of the tasking window is limited to 7 days from the current time and is set to the maximum window length by default. 3. **Set the image fidelity parameters** Image fidelity of the SAR data product is controlled by setting the Resolution and Looks parameters in the control panel. To understand the nuances of each image fidelity setting, see Tasking Parameters 101. See Pricing for cost per Resolution x Looks. 4. **Set the advanced tasking geometry parameters (optional)** By default, the Polarization, Grazing Angle, and Target Azimuth Angle are optimized to return opportunities that meet our high quality standards. However, users can optionally refine these parameters to fit their use case. If you have any questions about what parameters are best suited to your use case, please refer to our guides or contact [help@umbra.space](mailto:help@umbra.space). For definitions of the bolded terms above, please see the Tasking glossary. 5. **Assess tasking feasibility** Once the tasking parameters have been defined, click Check Feasibility to proceed. The following view displays a list of available accesses that would serve your request. Each item in the list can be expanded to show the details of the access. Click the Select button on the access you'd like to reserve to proceed. Canopy's feasibility system takes the current mission schedule into account and only returns access windows that are available for scheduling. 6. **Set a task name** In the right panel, set the Task Name. This field is searchable throughout Canopy. Optionally set the User Order ID as a user-defined unique identifier. 7. **Select a delivery method** The Data Delivery Method dictates where Canopy will deliver your tasked data products. "Canopy" is the default delivery method and means data will be available for download via the UI and API. Alternatively, you can select a predefined Delivery Configuration from the dropdown to have the data products delivered directly to your own storage. This is defined in detail in Canopy's API documentation. If a Delivery Configuration is chosen, the data will still be available for download in Canopy. 8. **Select data products** Select the data product format(s) from the Product Types list. GEC is compulsory and always delivered. For more information on all product types, see Delivered Product Types. You can also reach out to a Customer Success representative to set and update your preferred product types so that they're checked by default for tasking. These can still be modified on a per task basis too. Please be sure to make sure you're aware of pricing implications for each product type. Every data product type includes a json metadata file. This schema is defined at the following location [https://docs.canopy.umbra.space/docs/tasking#collect-metadata-schema](https://docs.canopy.umbra.space/docs/tasking#collect-metadata-schema). 9. **Submit tasking request** When ready, click Submit Task Request. Once submitted, the task will be validated and queued for scheduling. The scheduling system processes the task queue every 10 minutes. A status of "Scheduled" indicates that Umbra expects to be able to fulfill your order. A status of "Rejected" indicates that Umbra cannot fulfill your order. 10. **Check Task** Any time after creating your task, you can check on its status via the "Tasks" view. You can use the table filters to search the task by its name or several other parameters. From the table view, or by clicking into the Task Detail view, you can see the status of a task. 11. **Download your Data** When your task has reached "Delivered" status, it can be download from its detail view. Your Collect with a download button should show in the "Collects" tab where data can be retrieved.