Job Management
Get job status
Retrieve the status and metadata of a detection job.
GET /api/v1/jobs/{job_id}
Retrieve the current status of a detection job. Poll this endpoint until status becomes completed or failed.
Request
curl https://api.spcsft.com/api/v1/jobs/351e635d-7c25-4ae8-a2a5-60c01a6f434c \
-H "Authorization: Bearer sk_live_xxxxx"Path parameters
| Parameter | Type | Description |
|---|---|---|
job_id | string (UUID) | Returned from the detection endpoint. |
Response
Completed job
{
"job_id": "351e635d-7c25-4ae8-a2a5-60c01a6f434c",
"status": "completed",
"created_at": "2026-03-12T15:00:00Z",
"completed_at": "2026-03-12T15:32:10Z",
"result_path": "/api/v1/jobs/351e635d-7c25-4ae8-a2a5-60c01a6f434c/result.geojson",
"error_code": null,
"error_message": null,
"error": null
}Failed job
{
"job_id": "351e635d-7c25-4ae8-a2a5-60c01a6f434c",
"status": "failed",
"created_at": "2026-03-12T15:00:00Z",
"completed_at": "2026-03-12T15:31:15Z",
"result_path": null,
"error_code": "VALIDATION_ERROR",
"error_message": "Polygon area (52.6 km²) exceeds 50 km² limit for endpoint 'timeseries'",
"error": "VALIDATION_ERROR"
}Response fields
| Field | Type | Description |
|---|---|---|
job_id | string | Job UUID. |
status | string | pending / processing / completed / failed |
created_at | string | ISO 8601 timestamp. |
completed_at | string | null | ISO 8601 timestamp. null while pending/processing. |
result_path | string | null | GeoJSON download path. null unless completed. |
error_code | string | null | Machine-readable error code. See Errors. |
error_message | string | null | Human-readable error detail. Fixed message for 5xx errors. |
error | string | null | Deprecated. Same as error_code. Use error_code instead. |
Status values
| Status | Description |
|---|---|
pending | Queued, not yet started. |
processing | Currently running. |
completed | Done. Result available for 30 days. |
failed | Failed. See error for details. No credits charged. |
Polling guidance
Poll about once per minute. See How it works for per-endpoint timing recommendations.