Preview a request
Check the analysed area and credit cost before submitting a job.
POST /api/v1/analyze/{endpoint}/preview
Preview what a detection request would do before submitting it: which part of your AOI is expected to be analysed, and how many credits it will consume. No job is created and no credits are charged.
The request body is identical to the submission body for the same endpoint. Build one request object, preview it, then submit the same object unchanged.
Request
curl -X POST https://api.spcsft.com/api/v1/analyze/newbuilding/preview \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"satellite_id": "sentinel-1",
"polygon": "POLYGON((139.7 35.6, 139.8 35.6, 139.8 35.7, 139.7 35.7, 139.7 35.6))",
"date_start": "2024-01-01",
"date_end": "2026-03-01"
}'The {endpoint} path parameter accepts the same detection types as submission: ship, oilslick, newbuilding, disappearbuilding, timeseries. Parameters, required fields, and constraints are those of the corresponding detection endpoint.
Response
{
"endpoint_id": "newbuilding",
"area_sqkm": 80.65,
"coverage": {
"method": "estimated",
"requested_area_sqkm": 103.4,
"ratio": 0.78,
"polygon": "POLYGON((139.7 35.6, ...))"
},
"credits": {
"estimated": 1.03,
"balance": 480.0,
"sufficient": true
},
"warnings": [
{
"code": "LOW_AOI_COVERAGE",
"message": "Scenes cover only 78% of the requested area."
}
]
}| Field | Type | Description |
|---|---|---|
endpoint_id | string | Echo of the requested detection type. |
area_sqkm | number | null | Area the estimate is based on (km²). When coverage is present this is the area expected to be analysed; otherwise it is the area of the polygon you submitted. |
coverage | object | null | Expected analysed portion of your AOI, in the same structure as Get job status. Before submission it is always method: "estimated". Absent when it cannot be predicted — absent means unknown, not 100%. |
credits.estimated | number | null | Expected credit consumption. null means it cannot be determined before submission, not that the job is free — the reason arrives as a CREDITS_NOT_ESTIMABLE warning. |
credits.balance | number | Your current credit balance. |
credits.sufficient | boolean | null | Whether balance covers estimated. null when estimated is null. |
warnings | array | The warnings that can be determined before submission: LOW_AOI_COVERAGE and CREDITS_NOT_ESTIMABLE. The remaining scene-selection warnings only appear on the job itself. See Warnings. |
When can credits be estimated?
| Input pattern | Credits determined by | credits.estimated |
|---|---|---|
polygon — including ship / oilslick with polygon + date | Your polygon | Returned |
scene_id | The full scene footprint, not known until the scene is resolved | null, with a CREDITS_NOT_ESTIMABLE warning |
Actual consumption can be lower than the estimate: the estimate is based on your requested area, while the final charge excludes portions without usable data.
Coverage prediction
For newbuilding / disappearbuilding / timeseries, the preview runs the same scene selection as the actual job and reports the coverage of the scene that will be used, so the predicted ratio matches the post-job measured value up to the no-data margin inside the scene.
If the scene search fails or times out, the response omits coverage and still returns credits — a rough answer beats no answer.
Validation
The preview runs the same validation functions as submission, in the same order. Invalid bodies, malformed WKT, unsupported input patterns, area or date range over the limit, and missing permissions return the same status codes as the detection endpoint.
Three things are checked only at submission, so a successful preview does not guarantee the job starts:
- An insufficient balance — the preview returns
200with"sufficient": falseinstead of402, because finding out how much you are short is part of what a preview is for. - Whether a
polygon_idortif_idexists and is ready (404/409). - The concurrent-job limit (
429), which depends on what is running at that moment.