Getting Started

Authentication

Accessing Data

Constellation Tasking

Tasking Requests Overview Collection Tiers Collection Types Submitting a Tasking Request Submitting an Existing Tasking Request or Collect for Retasking Designating Collection Time Additional Information Tasking Request Status Cost Review and Approval Cancel a Task Tiles and Collects Searching Single and Repeat Tasking Requests

Mission Awareness

API

Tasking Requests

Overview

If suitable data over your area of interest doesn't exist in the archive, you can submit a request for new data to be collected by Capella's SAR satellite constellation.

To submit a new request, you will need to provide information on:

where you would like the data to be collected
when you would like the data to be collected
what collection type you would like to use
the frequency of the tasking request
a tasking tier to identify the importance of the tasking request for the scheduling system.

Once a tasking request has been submitted, Capella's tasking system will automatically determine whether it is possible to fulfill your tasking request. When a tasking request is accepted, the system will provide information on the status of the request. More information on the types of tasking available from Capella and how requests are scheduled is available on the Capella Support site.

Collection Tiers

Capella Space’s automated tasking system for repeat and single point and area tasks leverages a number of tasking (collection) tiers to denote the importance of a tasking request for the Scheduler.

Single and Area Tasking

Collection Tier	Description
urgent	Designed for time-sensitive situations where rapid collection speed is mission critical. Urgent tasks are considered for scheduling first. Minimum acquisition window is 24 hours.
priority	Optimal minimum acquisition window for situations when precise imaging geometries matter. Priority tasks are considered for scheduling after Urgent tasks. Minimum acquisition window is 72 hours.
standard	Provides assured data collection upon acceptance. Standard tasks are considered for scheduling after the Urgent and Priority tasks. Minimum acquisition window is 7 days.
flexible	Ideal for leveraging variations in capacity without the risk of interfering with tasks of higher importance. Flexible tasks can be added, shuffled, and removed from the schedule to accommodate tasks with higher importance. Customers set their own acquisition windows.

Repeat Tasking

Collection Tier	Description
routine	Get coverage on a regular basis. Offers premium importance for data collection when regularity and consistent imaging geometry are crucial. Customers set their own acquisition windows. Minimum repeat cycle is 24 hours.
flexible	Ideal for leveraging variations in capacity without the risk of interfering with tasks of higher importance. Flexible tasks can be added, shuffled, and removed from the schedule to accommodate tasks with higher importance. Customers set their own acquisition windows. Minimum repeat cycle is 24 hours.

For more information on Capella's tasking tiers and their role in scheduling and prioritization, see the Support articles for What are Capella's Tasking Tiers?, What is Capella's "No Bumping" Policy?, and Scheduling of Tasking Requests.

Collection Types

When submitting a tasking request, you will need to include the desired collection type. The collection type sets the collect mode, number of looks, and resolutions for the resulting imagery. The available collection types can be found by submitting:

GET https://api.capellaspace.com/collectiontypes

This will return the name of all the available collection types along with properties about those collection types.

Submitting a Tasking Request

Point Tasking Request

To submit a single tasking request using a point Area of Interest, you will make a request to the task endpoint. The request body is a GeoJSON feature, which includes properties describing the parameters for the tasking request:

POST https://api.capellaspace.com/task
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -71.09727327650678,
          42.34643585900935
        ]
      },
      "properties": {
        "taskingrequestDescription": "My first tasking request",
        "taskingrequestName": "Tasking Test 1",
        "windowOpen": "2024-10-01T00:00:00.000Z",
        "windowClose": "2024-10-08T00:00:00.000Z",
        "collectionTier": "standard",
        "collectionType": "spotlight",
        "collectConstraints": {
          lookDirection": "right",
          "ascDesc": "ascending",
          "orbitalPlanes": [45, 53],
          "offNadirMin": 5,
          "offNadirMax": 50,
          "azimuthAngleMin": 340,
          "azimuthAngleMax": 20,
          "localTime": "night"
          },
        },
        "preApproval": true,
        “customAttribute1”: “My New Project”,
        "customAttribute2”: “XYZ123”
      }

The geometry can be either a point. If you would like to use a polygon, follow the Area Tasking Request example. The taskingrequestName and taskingrequestDescription can be used to help characterize and describe the tasking request. The remaining properties define how the data will be collected:

windowOpen is a required field that should be set at the earliest time (UTC) you would like data collected
windowClose can optionally be set for a time longer than the collectionTier indicates, which will extend the imaging window for your request
collectionTier can be either urgent, priority, standard, or flexible and will indicate the importance of the tasking request for the scheduling system
collectionType indicates the desired collection type
localTime can be used to restrict the time of day at which the image is collected. This value is defined by either a pre-defined value or a list of time ranges, representing the seconds in the day when the collect can be taken. For more information, see the Designating Collection Time section.
preApproval will skip the tasking request cost review step if set to true
customAttribute1 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems
customAttribute2 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems

In addition, you can specify a number of collectConstraints to set the imaging geometry for the collect. In the example above, the tasking request nighttime with right looking, ascending, mid-inclination orbits, and a look angle between 5 degrees and 50 degrees. For any collectConstraints parameter not specifically defined, the default will be used.

lookDirection indicates the view angle, which can be right, left, or either
ascDesc indicates the orbit state, which can be ascending, descending, or either
orbitalPlanes is an array of orbital plane values that can be used to service the request, which can be 45, 53, or 97.
offNadirMin and offNadirMax indicate the angles between the sub-satellite point and the collect center point from the satellite to the target. The values for these parameters are defined in degrees, and the minimum value must not exceed the maximum.
azimuthAngleMin and azimuthAngleMax indicate the clockwise angle with respect to North in a topocentric geodetic ENZ coordinate system from the target to the satellite. The values for this parameter are defined in degrees and can be set as a range, wrap around (i.e. 340 to 20), or as the same value, if you have a specific viewing angle you would like to task for.

There are many other collectConstraints parameters that can defined, including the grazingAngleMin and grazingAngleMax. See the Support article for What are Capella's custom parameters? for more details.

The response will contain detailed information about your area tasking request, including additional information about the collect constraints set by the collectionType.

Area Tasking Request

To submit an area tasking request using a polygon Area of Interest, you will make a request to the task endpoint. The request body is a GeoJSON feature, which includes properties describing the parameters for the tasking request:

POST https://api.capellaspace.com/task
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              179.84893798828125,
              66.42553717157787
            ],
            [
              180.25543212890625,
              66.42553717157787
            ],
            [
              180.25543212890625,
              66.58430877083293
            ],
            [
              179.84893798828125,
              66.58430877083293
            ],
            [
              179.84893798828125,
              66.42553717157787
            ]
          ]
        ]
      },
      "properties": {
        "taskingrequestName": "Area Tasking Test 1",
        "taskingrequestDescription": "My first area tasking request",
        "windowOpen": "2022-11-18T00:00:00.000Z",
        "windowClose": "2022-12-29T00:00:00.000Z",
        "collectionTier": "standard",
        "collectionType": "stripmap_100",
        "preApproval": false,
        “customAttribute1”: “My New Project”,
        "customAttribute2”: “XYZ123”
      }
    }

The geometry can must be polygon. Multi-polygons and intersecting polygons are not accepted. The taskingrequestName and taskingrequestDescription can be used to help characterize and describe the tasking request. The remaining properties define how the data will be collected:

windowOpen is a required field that should be set at the earliest time (UTC) you would like data collected
windowClose can optionally be set for a time longer than the collectionTier indicates, which will extend the imaging window for your request
collectionTier can be either urgent, priority, standard, or flexible and will indicate the importance of the tasking request for the scheduling system
collectionType indicates the desired collection type. For area tasks, stripmap_100 is the sole collectionType accepted as the system will optimize the length of images to cover the AOI.
preApproval will skip the tasking request cost review step if set to true
customAttribute1 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems
customAttribute2 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems

The response will contain detailed information about your area tasking request, including additional information about the collect constraints set by the collectionType. For more information on the collection tiers available for single and area tasking, see the Capella Support site.

Repeat Tasking Request

To submit a repeat tasking request, you will make a request to the repeat-requests endpoint. The request body is a GeoJSON feature, which includes properties describing the parameters for the repeat tasking request:

POST https://api.capellaspace.com/repeat-requests
{ 
  "type": "Feature",
  "geometry":{
    "coordinates":[ 
      -118.22537899999998, 
      36.561082999999996 
    ], 
    "type":"Point" 
  }, 
  "properties":{ 
    "repeatRequestName":"Repeat Task Test 1", 
    "repeatRequestDescription":"My first repeat task request", 
    "repetitionProperties":{ 
      "repeatStart": "2024-10-01T01:02:20.093Z", 
      "repeatEnd":"2024-12-31T22:02:20.093Z",
      "repetitionInterval":3, 
      "maintainSceneFraming":true, 
      "lookAngleTolerance":10,
      "azimuthAngleTolerance": 10 
    }, 
    "collectionTier":"routine", 
    "collectionType": "spotlight_wide",
    "collectConstraints": {
      "orbitalPlanes": [97],
      "offNadirMin": 20,
      "offNadirMax": 40
    }
    "customAttribute1": "My New Project", 
    "customAttribute2": "XYZ123" 
  }
}

The geometry for repeat tasking can only be a point target. Polygon, multi-polygons and intersecting polygons are not accepted. The repeatRequestName and repeatRequestDescription can be used to help characterize and describe the repeat tasking request. The remaining properties define how the data will be collected:

repeatStart is the earliest date and time in UTC you would like data collected
repetitionInterval is the number of days between the start of derived requests. For example, a repetitionInterval equal to 5 means requests will open 5 days after the opening previous request
maintainSceneFraming is a flag to indicate that consistent geometries (look direction, orbit state, orbital plane) should be maintained across all acquisitions. Setting this parameter to true allows you to set the lookAngleTolerance and azimuthAngleTolerance.
lookAngleTolerance is the tolerance range for look angles that should be maintained across all acquisitions, if maintainSceneFraming is enabled
azimuthAngleTolerance is the tolerance range for azimuth angles that should be maintained across all acquisitions, if maintainSceneFraming is enabled
collectionTier can be either routine or flexible and will indicate your preference for the collection importance for the scheduling system
collectionType indicates the desired collection type
customAttribute1 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems 
customAttribute2 is an optional custom attribute to help you track a Capella task with your own metadata or internal systems

Repeat tasks have three available triggers to end the series:

repetitionCount is the total number of acquisitions for a repeat series. Once this number is met with completed acquisitions, the series will end.
repetitionEnd is the latest date and time in UTC you would like data collected
repetitionInterval alone without either of the other two parameters specifies means you would like data collected until you send a PATCH request to cancel the repeat series

In addition, you can specify a number of collectConstraints to set the imaging geometry for the collect. In the example above, the request is for a Spotlight Wide image taken anytime by a satellite in a 97 degree orbit with a look angle between 20 degrees and 40 degrees. Because the request specifies the maintainSceneFraming as true, all collects created by the repeat series will be collected with the same orbit state and look direction. This repeat series will generate a tasking request every three days from October 1, 2024 to December 31, 2024. There are many other collectConstraints parameters that can defined, including the grazingAngleMin and grazingAngleMax. See the Support article for What are Capella's custom parameters? for more details.The response will contain detailed information about your repeat tasking request, including the specific constraints used for imaging. For more information on the collection tiers available for repeat tasking, see the Capella Support site.

Submitting an Existing Tasking Request or Collect for Retasking

Retasking a Tasking Request or a Single Tasking Request from a Repeat Series

If you have an existing tasking request or a single task from a repeat series that you would like Capella to recollect for you, you can submit the existing taskingRequestId for retasking by making a request to the POST task/{taskingRequestId}/retask endpoint. This request will generate a one-time tasking request with the point target from the original tasking request. This endpoint cannot be used to retask area (polygon) tasking requests.

The request can be sent with an empty GeoJSON feature body or with a select number of properties to add identifying information to the request or change the Tasking Tier and collection time parameters of the request:

POST https://api.capellaspace.com/task/{taskingRequestID}/retask
    {
    "retaskRequestName": "My first retasking request",
    "retaskRequestDescription": "Retasking Test 1",
    "windowOpen": "2023-12-13T00:49:59.944Z",
    "windowClose": "2023-12-14T00:49:59.944Z",
    "collectionTier": "urgent",
    "archiveHoldback": "30_day"
    }

All the available properties are optional. If not specified, the values will default to those from the original tasking request. The original taskingRequestId will be appended to the retaskRequestDescription, if specified, or will be appended to the taksingRequestDescription from the original tasking request, if not specified. For example, the Retasking Test 1 specified above will become Retasking Test 1 – TRID: taskingRequestId. If the original tasking request had a taskingRequestDescription of Nighttime collect and a new description is not specified, the description of the new tasking request will become Nighttime collect – TRID: taskingRequestId. This is to provide the user with an easy way to link between the original and new tasking requests.

The other available parameters can be used to set the importance and timing of when the data should be collected:

retaskRequestName and retaskRequestDescription can be used to help characterize and describe the new tasking request
windowOpen can optionally be set to a specific time in UTC you would like data collection to start. If not specified, the windowOpen will automatically default to the date and time of submission.
windowClose can optionally be set for a time longer than the collectionTier indicates, which will extend the acuqisiton window for your request
collectionTier can be optionally set indicate the importance of the tasking request for the scheduling system and can be set to urgent, priority, standard, or flexible. If not specified, the collectionTier will default to the tier used in the original request.
archiveHoldback sets the timeline for which the resulting collect is made available in the Capella archive and can be set to none, 30_day, 1_year, and permanent. If not specified, the archiveHoldback will default to the value used in the original request.

All other properties, including the collectConstraints, for the retasking request are inherited from the original tasking request. The response will contain detailed information about your new single tasking request, including the specific constraints used for imaging.

Retasking an Image from the Archive

If you have an existing collection or have found an image from the Capella archive that you will like Capella to recollect for you, you can submit the existing collectId for retasking by making a request to the POST collects/{collectId}/retask endpoint. This request will generate a one-time tasking request with a point target constructed from the center point of the original collection. This endpoint cannot be used to create a repeat tasking request.

The request can be sent with an empty GeoJSON feature body or with a select number of properties to add identifying information to the request, change the Tasking Tier and collection time parameters, and modify the look angles of the request:

POST https://api.capellaspace.com/collects/{collectID}/retask
    {
      "retaskRequestName": "My first recollect request",
      "retaskRequestDescription": "Collect Retasking Test 1",
      "windowOpen": "2023-07-20T00:49:59.944Z",
      "windowClose": "2023-07-21T00:49:59.944Z",
      "collectionTier": "priority",
      "offNadirMin": "15"
      "offNadirMax": "50"
      "archiveHoldback": "1_year"
    }

All the available properties are optional. If not specified, the values will default to Retask Request for the retaskRequestName, standard for the collectionTier, the date and time of submission for the Window Open, and the minimum window duration of the standard tier for the windowClose. The offNadirMin and offNadirMax will default to -/+ 5 degrees from the look angle of the original collectId. Addtionally, the original collectId will be appended to the retaskRequestDescription. For example, Collect Retasking Test 1 will become Collect Retasking Test 1 – CID: collectId. If the repeatRequestDescription is not specified, then the description of the new tasking request will be – CID: collectId. This is to provide the user with an easy way to link between the original collection and the new tasking requests.

The other available properties can be used to define when the data will be collected or to change the look angles to a user-specified range:

retaskRequestName and retaskRequestDescription can be used to help characterize and describe the new tasking request
windowOpen can optionally be set to a specific time in UTC you would like data collection to start or will automatically default to today, if not specified
windowClose can optionally be set for a time longer than the collectionTier indicates, which will extend the acquisition window for your request
collectionTier indicates your preference for data to be collected within a particular timeframe and can be set to urgent, priority, standard, or flexible. If not specified, the new tasking request will default to standard.
offNadirMin will default to -5 degrees from the look angle of the original collection to provide consistent imaging geometries, if the property is not included in the request. You can change this to be any number between 5 and 50, although it must be smaller than the offNadirMax.
offNadirMax will default to +5 degrees from the look angle of the original collection to provide consistent imaging geometries, if the property is not included in the request. You can change this to be any number between 5 and 50, although it must be larger than the offNadirMin.
archiveHoldback sets the timeline for which the resulting collect is made available in the Capella archive and can be set to none, 30_day, 1_year, and permanent. If not specified, the archiveHoldback will default to the value set by your organization's contract.

The response will contain detailed information about the new single tasking request.

Geometrically Similar Collects

All tasking requests created through the collects/{collectID}/retask endpoint are given the productCategory of custom. This ensures the tasking request can be constructed to match the original collection as closely as possible. It also provides the user with the option to customize the look angles rather than leverage the default 10 degree (+/-5) look angle tolerance.

For example, if the original collection had a look angle of 32 degrees, the collection created from the new tasking request could have a look angle between 27 and 37 degrees. If you set the offNadirMin to 30 and do not specify an offNadirMax, the resulting collection would have a look angle between 30 and 37. If you set the offNadirMin to 5 and set the offNadirMax to 30, the resulting collection would have a look angle between those two values even though the original collection had a look angle of 32 degrees.

Retasking a Repeat Tasking Request

If you have an existing repeat tasking request that you would like Capella to recollect for you, you can submit the existing repeatRequestId for retasking by making a request to the POST repeat-request/{repeatRequestId}/retask endpoint. This request will generate a new repeat tasking request with the point target from the original repeat tasking request.

POST https://api.capellaspace.com/repeat-request/{repeatRequestID}/retask
    {
        "retaskRequestName": "My first repeat retasking request",
        "retaskRequestDescription": "Repeat Retasking Test 1",
        "repeatStart": "2023-12-13T00:49:59.944Z",
        "repetitionInterval": 3,
        //"repeatEnd": "2023-02-13T00:49:59.944Z",
        //"repetitionCount": 5,
        "untilCanceled": true,
        "collectionTier": "flexible",
        "archiveHoldback": "30_day"
    }

All the available properties are optional. If not specified, the values will default to those from the original repeat tasking request. The original repeatRequestId will be appended to the retaskRequestDescription, if specified, or will be appended to the repeatRequestDescription from the original repeat request, if not specified.

For example, the Repeat Retasking Test 1 specified above will become Repeat Retasking Test 1 – RRID: repeatRequestId. If the original repeat request had a repeatRequestDescription of Airplane monitoring and a new description is not specified, the description of the new repeat request will become Airplane monitoring – RRID: repeatRequestId. This is to provide the user with an easy way to link between the original and new repeat tasking requests.

The other available parameters can be used to add identifying information to the new repeat tasking request, set the importance of when the data should be collected by changing the Tasking Tier, or modify the end trigger for the series:

retaskRequestName and retaskRequestDescription can be used to help characterize and describe the new tasking request
repeatStart can optionally be set to a specific time in UTC you would like data collection to start. If not specified, the repeatStart will automatically default to the date and time of submission.
repetitionInterval is the number of days between the start of derived requests. For example, a repetitionInterval equal to 3 means requests will open 3 days after the opening previous request.
repeatEnd is one of three end triggers for a repeat request. If you provide a date, the repeat request will continue collecting imagery until the date is met.
repetitionCount is the second available end triggers for a repeat series. If you include this property, the total number of acquisitions for a repeat series will be set. Once this number is met with completed acquisitions, the series will end.
untilCanceled is the third available end triggers for a repeat series. If you include this property and set it to true, the new repeat request will continue until you send a PATCH request to cancel the repeat series
collectionTier can be optionally set indicate the importance of the tasking request for the scheduling system and can be set to either routine or flexible. If not specified, the collectionTier will default to tier used in the original request.
archiveHoldback sets the timeline for which the resulting collect is made available in the Capella archive and can be set to none, 30_day, 1_year, and permanent. If not specified, the archiveHoldback will default to the value used in the original request.

In the above request, untilCanceled is set to true while neither the repeatEnd nor the repetitionCount are specified. Therefore, the new repeat request will continue until you send a PATCH request to cancel the repeat series. (Remove // from in front of one of the other two properties and either add // before or remove the untilCanceled parameter to change the repeat end trigger.)

The response will contain detailed information about your new repeat tasking request, including the specific constraints used for imaging.

Geometrically Similar Collects

All other properties, including the collectConstraints, for the new repeat tasking request are inherited from the original repeat request. If the original repeat request included maintainSceneFraming: enabled or a lookAngleTolerance other than null, those constraints will be applied to the new repeat request and the Capella system will collect a series of geometrically similar collects within the new series. It will not create a new series that is geometrically similar with the original series. If you need to resubmit a tasking request to generate cohesive images, then you should use the Retask an image from the archive endpoint.

Designating Collection Time

You can designate your single and repeat tasking request should only be collected during specific times of the day by using the localTime parameter in the collectConstraints object of the tasking request.

The localTime parameter accepts either pre-defined string values or custom array values, representing the seconds in the day during which the collect can be taken. This parameter is available for all imaging modes and product categories and can be used to reduce the acquisition window duration to be shorter than the minimum for your selected collectionTier.

Pre-Defined Values

Three pre-defined collection times can be specified by submitting the string value as part of your collectConstraints.

"collectConstraints": {
    "localTime": “night”
  }

These times are:

day: between 6AM and 6PM (06:00 – 18:00) local time
night: between 6PM and 6AM (18:00 – 6:00) local time
anytime: the full 24-hour period of a day (0:00-24:00)

Daylight Saving Time is considered when determining the collection time. The time zone is based on the center point of the tasking request area of interest (AOI).

The default localTime for repeat and single tasking requests is anytime. This value will be returned in the response if you do not specify one of the other pre-defined values or a custom array.

Custom Values

If you would like to provide a custom time for collection, you can specify an array using the same localTime parameter. The parameter is structured to accepted seconds in the day where 0 is the first second of the day and 86400 is the last second in the day. This calculation can be done by accounting for 60 seconds per minute, 60 minutes per hour, for however many hours from 12AM (0:00) you would like.

For example, if you want your tasking request to be collected between 4AM and 5PM (17:00), you would configure your request to include the following:

"collectConstraints": {
    "localTime": [14400.0, 61200.0]
  }

Your custom array value will then be returned in the response. If you’re custom array aligns with the pre-defined times set by the day, night, or anytime string values, then that value will be returned in the response instead.

Additional Information

For more information on constellation tasking requests, see the Support site for Tasking as well as the API reference for Tasking.

Tasking Requests

.css-1r0pe6c{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1r0pe6c:hover{-webkit-text-decoration:underline;text-decoration:underline;}Overview

Overview