REST API

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

• The image is chosen from a period around your date, not only on the exact date. date is 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_clouds removes 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_range defaults to 7 days (maximum 90), and images up to 3 days after date are 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_credits and remaining_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_range and max_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

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:

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: 0 and 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.

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:

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.

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:

Old Versions

Articles for earlier releases of the API, kept for reference:

• Version 1.0
• Version 0.2