How it works

Satellite imagery analysis takes minutes to tens of minutes depending on the model and area. Every SateAIs detection endpoint is asynchronous: you submit a job, poll for its status, then fetch the result.

The three-step lifecycle

1. POST /api/v1/detect/{type}                →  receive job_id (status = "pending")
2. GET  /api/v1/jobs/{job_id}                →  poll until status = "completed"
3. GET  /api/v1/jobs/{job_id}/result.geojson →  fetch the GeoJSON result (302 redirect to S3)

Job statuses

Recommended polling interval

Poll every ~1 minute. Polling faster increases load without accelerating completion and may trigger rate limits.

Runtime depends mostly on analyzed area. The ranges below reflect small-to-large AOIs observed in production. Submit a small test job first to gauge the upper bound for your workload.

Result retention

Results are stored for 30 days after completion. After that, GET /api/v1/jobs/{job_id}/result.geojson returns 410 Gone. The job metadata itself (status, timestamps) is retained indefinitely.

Failure handling

If a job fails:

• status transitions to failed.
• The error field contains a machine-readable code and human-readable message.
• No credits are charged for failed jobs.
• Clients should surface the error code to users and optionally retry.

See Errors for the full list of error codes.

Next steps