REST API
Submit S2DR3 jobs with the new image selection (date range and cloud limit), credits and clearer errors, then check job state and credits.
Latest release: v1.1
The API lets you submit asynchronous S2DR3 processing jobs. A job submission returns metadata immediately. The generated products appear in the corresponding storage location after processing.
Changelog
16 November 2026: vector files with aoi_file
aoi_fileis an alternative toaoi. Send the content of a GeoJSON file, or the text of a KML or GPX file, instead of a bounding box. Send one of the two, never both. See Send a Vector File.- It is always one job. The box around your area must fit one job (about
150 km2). A larger area, or a file with several separate parts, is refused with
a 400 that points to the SDK (
--aoi_file). - Every area is at least 150 m wide. A line becomes a strip 150 m wide, a narrower polygon is grown until it is wide enough, and a point becomes a 900 m square. You are charged for the widened area.
- The price follows the area of your polygon: its area in km2 (widened where it is narrower than 150 m) times the rate of its region, rounded up, at least 1 credit.
- The output is cropped to your shape: there is no data outside it. The true-colour file has an alpha band that is 0 outside the shape.
- New response fields:
batch_id,area_km2,rateandprice_credits. - A STAC item file for each product, and the response fields
stac_itemandstac_job. See The STAC Item.
Version 1.1
- The image is chosen from a period around your date, not only on the exact
date.
dateis the target date. With Version 1.0 the request failed if no scene existed on that exact date. - A cloud limit now means a limit.
max_cloudsremoves every image with more cloud cover over your AOI than the limit. When you set no limit, the clearest image in the period is used. - Default search period:
date_rangedefaults to 7 days (maximum 90), and images up to 3 days afterdateare included. - Unusable images are skipped automatically instead of failing the job.
- Credits are part of the workflow: credits are reserved when you submit a
job and charged when it completes. Repeating the same area and image date with
the same API key is free. The response shows
requested_creditsandremaining_total_balance. - Your balance and latest jobs are available from
GET /jobs/{API_KEY}, and the job state includes the credit status of the job. - Clear error messages with status codes 400, 401, 402, 404 and 503.
- Areas that are too large are refused (status 400) before any credits are reserved; keep the area to about 150 km2 (12 x 12 km).
- Results that cannot be saved are reported. If the output files of a job cannot be stored, the job now ends as failed (and its credits are returned) instead of ending as completed with files missing.
- Dates must be written
YYYY-MM-DD(a month or day without its leading zero is accepted). - A valid API key is required to submit a job.
The following were introduced in earlier releases and are still current:
- 1.0: the API runs on AWS and accommodates a large number of parallel jobs.
- 0.2: parameters
date_rangeandmax_clouds.
If you are moving from Version 1.0, read the changelog above first.
Before You Start
For instructions on how to generate your API key, see API Access & Keys. A valid API key is required to submit a job.
Call the API at:
https://api.gamma.earth/jobs/{API_KEY}
Replace {API_KEY} with your API key. Every example below uses this endpoint.
If your integration still posts to the endpoint used before the move to AWS, see the migration notes in Version 1.0.
Submit a Job
Endpoint:
https://api.gamma.earth/jobs/{API_KEY}
Method:
POST
Example payload:
{
"date": "2024-01-31",
"date_range": 30,
"max_clouds": 10,
"aoi": "-74.165 4.690 -74.125 4.715"
}
Request Parameters
| Parameter | Required | Description |
|---|---|---|
date | Yes | Target date, written YYYY-MM-DD. Gamma Earth chooses the Sentinel-2 image around this date, as described in How the Image Is Chosen below. |
aoi | Yes, unless you send aoi_file | Bounding box for the area of interest in minx miny maxx maxy order (longitude and latitude). The area should not exceed 150 km2 (about 12 x 12 km) and should fit within a single Sentinel-2 scene. |
date_range | No | Number of days before date to search. Whole number from 0 to 90. Default: 7. Images up to 3 days after date are also considered. |
max_clouds | No | Maximum cloud cover over your AOI, in percent (0 to 100). Default: 100 (no limit). |
aoi_file | Yes, unless you send aoi | The area in a file: the content of a GeoJSON file (a FeatureCollection, a Feature or a geometry, as a JSON object) or the text of a KML or GPX file (as a JSON string). Send either aoi or aoi_file, never both. See Send a Vector File. |
Send a Vector File
Use aoi_file instead of aoi when your area is not a simple box: a polygon, a
line such as a GPS track, or a point.
- Accepted: the content of a GeoJSON file, or the text of a KML or GPX file. Not accepted: shapefiles, KMZ, GML, WKT and CSV.
- Positions with an altitude (
lon,lat,alt, as in Google Earth KML or GPX elevation) are accepted; the altitude is ignored. - Every area is at least 150 m wide. A line becomes a strip 150 m wide (75 m on each side), a polygon narrower than that is grown until it is wide enough, and a point becomes a 900 m square. You are charged for the widened area. There is no surcharge and no option to set the width.
- The API always creates one job. The box around the area must fit one job,
which is about 150 km2. An area that needs more than one job is refused with a
400 that names the SDK. A file with several separate parts (for example a
GPX with a track and a waypoint, or two polygons even a kilometre apart) also
needs one job for each part, so it is refused too: send one part at a time, or
use the SDK (
--aoi_file; see Python SDK). - Limits: the file at most 150 KB, and in all at most 2,500 vertices and 500 features or parts. A GPS track with more than about 1,200 points must be simplified first, because the line is widened before it is counted.
- Areas over the sea or outside 80°S to 84°N are refused, and a shape that crosses the antimeridian (180° longitude) must be split.
Example with GeoJSON:
{
"date": "2025-07-02",
"aoi_file": {
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [[[9.30, 50.50], [9.32, 50.50], [9.32, 50.52], [9.30, 50.52], [9.30, 50.50]]]
}
}
}
Example with the text of a KML file:
{
"date": "2025-07-02",
"aoi_file": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><kml xmlns=\"http://www.opengis.net/kml/2.2\"><Placemark><LineString><coordinates>9.30,50.50,0 9.32,50.52,0</coordinates></LineString></Placemark></kml>"
}
date, date_range and max_clouds work as for a box job.
The answer is a normal job answer (see Example Response below) with four more
fields: batch_id, area_km2, rate and price_credits.
Example answer for another, smaller polygon (1.29 km2, in a region with rate 0.75, so 1 credit):
{
"job_id": "a3ae0fb7-df55-11f1",
"batch_id": "b34dc0d30a9e9dbf1fe1c38b48c4fa62e4",
"price_credits": 1,
"requested_credits": 1,
"area_km2": 1.289422,
"rate": 0.75,
"pid": "T32UMB-02da1cef8-20250702"
}
The answer also carries the usual fields of a job answer: date,
cloud_cover, remaining_total_balance, save_path_S3_TCI and the STAC links.
How the Image Is Chosen
Gamma Earth looks at the Sentinel-2 images acquired from date - date_range
days up to 3 days after date. Cloud cover is measured over your AOI, not over
the whole Sentinel-2 tile. Then:
| Your request | Image used |
|---|---|
No max_clouds (or max_clouds set to 100) | The clearest image in the period. If several are equally clear, the one closest to date; if two are equally close, the later one. |
max_clouds below 100 | Images with more cloud cover than your limit are dropped. Among the rest, the image closest to date. |
Images whose data is not available for processing are skipped automatically, and the next best image is used.
If no image qualifies, the request is refused with an explanation and nothing is charged. See Errors below.
The response tells you which image was used: date is its acquisition date and
cloud_cover is its cloud cover over your AOI, in percent.
Credits
Each job uses credits from the balance of your API key. The amount depends on the area of your AOI and its region; see How Credits Work.
- When you submit a job, the credits are reserved. They are charged when the job completes, and returned if the job fails.
- If your balance is not enough, the job is refused and nothing is reserved.
- Processing the same area on the same image date again with the same API key
is free. The response then contains
credits_charged: 0and a short note. The first job must have completed for the repeat to be free; a repeat submitted while the first job is still running is reserved as usual and returned when it completes.
With aoi_file:
- Price = the area of your polygon in km2 x the rate of its region, rounded up, at least 1 credit. The rates are 1.0, 0.75 or 0.5 by region, and a shape over several countries takes the highest rate. Example: a polygon of 1.29 km2 in a region with rate 0.75 costs 1 credit.
- The credits are reserved when the job starts and charged only if it completes.
The response shows
price_credits. - A repeat is free: the same shape, image date and API key is the same product
(same
pid) and costs nothing. The same shape sent through the SDK is the same product. A plainaoibox job names its product by the box, so it is not a repeat of a shape job. - Your balance must cover the whole price when the job starts, even for a repeat that turns out to be free.
Example Response
The API returns job metadata, not the processed data itself.
{
"uid": "xxxx",
"job_id": "a3781528-90c4-11f1",
"date": "20240118",
"MGRS": "18NWL",
"ISO": "CO",
"aoi": "-74.165 4.690 -74.125 4.715",
"sdk": false,
"save_path_S3_TCI": "s3://s2dr3-output/CO/T18NWL/T18NWL-200b906d1-20240118/S2L2Ax10_T18NWL-200b906d1-20240118_TCI.tif",
"cloud_cover": 1,
"sid": "200b906d1",
"pid": "T18NWL-200b906d1-20240118",
"no_bands": "10",
"make_preview": "true",
"requested_credits": 8,
"remaining_total_balance": 992
}
Important response fields:
| Field | Description |
|---|---|
job_id | Identifier used to check processing state. |
date | Acquisition date of the image that was chosen, YYYYMMDD. |
cloud_cover | Cloud cover of that image over your AOI, in percent. |
save_path_S3_TCI | S3 path for the super-resolved true-color dataset. Download your results from here. |
pid | Product identifier for the generated scene: the area and the image date. |
requested_credits | Credits reserved for this job. |
remaining_total_balance | Your balance after the reservation. |
credits_charged, credits_note | Present instead of requested_credits when the job is a free repeat. |
batch_id, area_km2, rate, price_credits | Only for an aoi_file job: the plan the job belongs to, the area charged in km2, the rate of its region and the price in credits. |
stac_item, stac_job | Addresses of the product's STAC item and of the job's collection. See The STAC Item. |
Errors
When a request cannot be accepted, the API answers with an HTTP status code and
a JSON body with an error field. Nothing is reserved or charged.
| Status | Meaning | Example message |
|---|---|---|
| 400 | A value is invalid: date, date_range, max_clouds, an identifier, or the area is too large. | max_clouds must be a number between 0 and 100. / The area of interest is too large for one job (about 210 km2). Use an area of about 150 km2 or less (for example 12 x 12 km), or split it into several requests. |
| 401 | The API key is missing, not valid, inactive or expired. | Invalid API key. / This API key is inactive or has expired. Add credits or create a new key in your Gamma Earth account (https://app.gamma.earth/plans). |
| 402 | Your balance is not enough for the job. | Not enough credits: this job needs 25 credits and you have 10. Add credits in your Gamma Earth account (https://app.gamma.earth/plans). |
| 404 | No image meets your date range and cloud limit, or the job does not exist. | No image found between 2024-01-01 and 2024-02-03 ... The clearest image in this period has 12% cloud cover; try a larger date_range or a higher max_clouds. |
| 503 | The credits could not be reserved for a temporary reason. | Unable to reserve credits for this job. Please try again. |
Errors that only aoi_file can give:
| Status | Message |
|---|---|
| 400 | Send either aoi or aoi_file, not both. |
| 400 | This area needs N jobs: the API runs one job per request, for an area whose box is at most about 14 x 14 km (about 150 km2). Use the SDK (--aoi_file) for larger areas. (also for a file with several separate parts) |
| 400 | aoi_file is larger than 150 KB: simplify the shape or send fewer features. |
| 400 | aoi_file must be the content of a GeoJSON file (a FeatureCollection, a Feature or a geometry) or the text of a KML or GPX file. |
| 400 | more than 2500 vertices: simplify the shape / more than 500 features: send fewer, or merge them / a DOCTYPE is not allowed in a KML or GPX file / the file holds no geometry |
| 402 | Not enough credits: this parent job needs N credits and you have M. Add credits in your Gamma Earth account (https://app.gamma.earth/plans). |
| 503 | The planner is busy or unavailable. Please try again in a minute. Nothing is reserved; try again. |
The date, date_range and max_clouds messages of a box job apply here too.
Check Job State
Append the job_id from the submission response to your endpoint:
https://api.gamma.earth/jobs/{API_KEY}/{job_id}
Method:
GET
Example response:
{
"job_id": "a3781528-90c4-11f1",
"state": "completed",
"credits_status": "COMMITTED",
"credits_requested": 8,
"credits_used": 8,
"reserved_at": "2026-10-14T09:12:05",
"pid": "T18NWL-200b906d1-20240118"
}
credits_status is PENDING while the job runs (credits reserved, not yet
charged), COMMITTED when they were charged and RELEASED when they were
returned to your balance. A free repeat has no credit fields.
Check Your Credits
To see your balance and your latest jobs, send a GET request to your endpoint
without a job_id:
https://api.gamma.earth/jobs/{API_KEY}?limit=20
limit is optional (default 50, maximum 200). Example response:
{
"credits": {
"purchased_balance": 917,
"bonus_balance": 75,
"total_balance": 992
},
"jobs": [
{
"job_id": "a3781528-90c4-11f1",
"pid": "T18NWL-200b906d1-20240118",
"credits_status": "COMMITTED",
"credits_requested": 8,
"credits_used": 8,
"reserved_at": "2026-10-14T09:12:05",
"release_reason": null
}
]
}
For what the balance includes, see Credit Balance and History.
Download Outputs
Download your results from save_path_S3_TCI. The response returns the S3
path for the true-color product, but the same S3 directory holds every
product generated for the job. Swap the filename to fetch the others, using
the job's pid:
| Filename | Product | Resolution |
|---|---|---|
S2L2A_<pid>_TCI.tif | True color | Sentinel-2 source |
S2L2A_<pid>_MS.tif | Multispectral | Sentinel-2 source |
S2L2A_<pid>_NDVI.tif | NDVI | Sentinel-2 source |
S2L2A_<pid>_IRP.tif | Infrared pseudo-color | Sentinel-2 source |
S2L2Ax10_<pid>_TCI.tif | True color | Super-resolved (x10) |
S2L2Ax10_<pid>_MS.tif | Multispectral | Super-resolved (x10) |
S2L2Ax10_<pid>_NDVI.tif | NDVI | Super-resolved (x10) |
S2L2Ax10_<pid>_IRP.tif | Infrared pseudo-color | Super-resolved (x10) |
A job made with aoi_file is cropped to your shape. Outside it the files
hold no data: the pixels are 0. The true-colour (TCI) file has an alpha band
(4 bands) that is 0 outside the shape, so GIS software draws those pixels
transparent. The multispectral file has no alpha band and uses 0 as no data. All
eight products are
under the same S3 path as for a box job, and nothing uncropped is published for
such a job.
The STAC Item
Every product the API makes has an item.json in its output folder, next to the
product files. It is a STAC item: it describes the product
(its area, date and cloud cover) and lists its files. Products made before this
update have no item file. The job answer carries stac_item and stac_job, the
addresses of the item and of the job's collection; send your API key in the
X-API-Key header when you read them.
Old Versions
Articles for earlier releases of the API, kept for reference: