Job Management
List jobs
Retrieve your most recent detection jobs, optionally filtered by status and endpoint.
GET /api/v1/jobs
List your most recent detection jobs. Filter by status and endpoint_id, adjust the page size with limit. Always sorted newest first.
The endpoint is designed for building "Recent jobs" panels in dashboards, CLI listings, and QGIS plugin history views without having to remember job_ids.
Request
curl "https://api.spcsft.com/api/v1/jobs?status=completed&limit=10" \
-H "Authorization: Bearer sk_live_xxxxx"Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | (all) | Filter by status. Comma-separated for multiple values (pending,processing). Allowed: pending / processing / completed / failed. |
endpoint_id | string | (all) | Filter by detection endpoint. Comma-separated for multiple (ship,oilslick). Allowed: ship / oilslick / newbuilding / disappearbuilding / timeseries. |
limit | integer | 30 | Maximum number of jobs to return. Must be between 1 and 30. |
Filter semantics
- Values are strict lowercase.
Pendingreturns400. - Duplicate values are deduplicated (
?status=pending,pendingbehaves as?status=pending). - Empty segments are ignored (
?status=,,pending,,behaves as?status=pending). - Comma-separated only. Repeated keys (
?status=pending&status=processing) will only apply the last value — always join with commas instead. - Unknown query parameters are silently ignored.
Response
{
"jobs": [
{
"job_id": "351e635d-7c25-4ae8-a2a5-60c01a6f434c",
"endpoint_id": "ship",
"satellite_id": "sentinel-1",
"status": "completed",
"created_at": "2026-06-29T10:00:00Z",
"completed_at": "2026-06-29T10:30:00Z",
"credits_used": 120.0,
"area_sqkm": 42.5,
"lat": 35.68,
"lon": 139.76,
"request_params": {
"scene_id": "S1A_IW_GRDH_1SDV_...",
"polygon": "POLYGON((...))",
"date": "2026-06-29",
"date_direction": "nearest"
},
"result_path": "/api/v1/jobs/351e635d-7c25-4ae8-a2a5-60c01a6f434c/result.geojson",
"error_code": null,
"error_message": null
}
]
}Response headers
| Header | Value | Reason |
|---|---|---|
Cache-Control | private, no-store, no-cache, must-revalidate | Prevents intermediate proxies from caching per-user job lists. |
Vary | Authorization | Ensures cache keys stay separated per API key. |
Response fields
| Field | Type | Description |
|---|---|---|
jobs | array | Job items, newest first. Empty array if you have no jobs. |
jobs[].job_id | string (UUID) | Job identifier. |
jobs[].endpoint_id | string | Detection endpoint (ship, newbuilding, ...). |
jobs[].satellite_id | string | null | Satellite (sentinel-1). May be null for endpoints that don't tie to a single satellite. |
jobs[].status | string | pending / processing / completed / failed. |
jobs[].created_at | string | ISO 8601 UTC (always with Z suffix). |
jobs[].completed_at | string | null | ISO 8601 UTC. null while pending/processing. |
jobs[].credits_used | number | null | Credits charged for the job. null while pending. |
jobs[].area_sqkm | number | null | Processed area. null while pending. |
jobs[].lat | number | null | Latitude of the scene / AOI centroid. null while pending. |
jobs[].lon | number | null | Longitude of the scene / AOI centroid. null while pending. |
jobs[].request_params | object | null | The parameters you passed to POST /api/v1/analyze/{endpoint}. Shape depends on endpoint_id; useful for redrawing the polygon or re-running with tweaks. Treat every string value as untrusted — escape before inserting into HTML. |
jobs[].result_path | string | null | Result download path (.geojson). null unless status=completed. |
jobs[].error_code | string | null | Machine-readable error code. See Errors. |
jobs[].error_message | string | null | Human-readable error detail. 5xx errors return a fixed generic message — inspect error_code for the actual category. |
Ordering and paging
- Sort is fixed:
created_at DESC, job_id DESC. The secondary sort byjob_idguarantees a deterministic order when multiple jobs share the samecreated_at. - There is no cursor / offset in v1. Requesting
?limit=30always returns the 30 newest jobs. If you need older history, request individual jobs viaGET /api/v1/jobs/{job_id}— you must keep thejob_idyourself.
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION_ERROR | Invalid status / endpoint_id value, non-integer / out-of-range limit, or a query parameter value longer than 128 characters. |
401 | UNAUTHORIZED | Missing or invalid Authorization header. |
See Errors for the full error contract.
Examples
Most recent 30 jobs
curl https://api.spcsft.com/api/v1/jobs \
-H "Authorization: Bearer sk_live_xxxxx"Only the latest completed job
curl "https://api.spcsft.com/api/v1/jobs?status=completed&limit=1" \
-H "Authorization: Bearer sk_live_xxxxx"In-flight ship / oilslick jobs
curl "https://api.spcsft.com/api/v1/jobs?status=pending,processing&endpoint_id=ship,oilslick" \
-H "Authorization: Bearer sk_live_xxxxx"