Poll a background process job

GET

/v1/process/jobs/{jobId}

const url = 'https://api.satellitedata.net/v1/process/jobs/3f2a9c1e5b7d4e0f8a6b2c4d1e3f5a7b';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.satellitedata.net/v1/process/jobs/3f2a9c1e5b7d4e0f8a6b2c4d1e3f5a7b \
  --header 'X-API-Key: <X-API-Key>'

Lean extension: the job’s status (queued, running, done or failed). When done it lists the files with fresh one-hour links, also as result links; when failed, error is a problem object. Jobs are kept for a day.

Authorizations

ApiKey

Parameters

Path Parameters

jobId

required

string

/^[0-9a-f]{32}$/

Job id from POST /v1/process/jobs.

Example

3f2a9c1e5b7d4e0f8a6b2c4d1e3f5a7b

Responses

200

The job.

application/json

A background process job (lean extension).

object

required

Job id.

string

status

required

Job status.

string

Allowed values: queued running done failed

created

Creation time.

string

updated

Last update.

string

files

When done: the GeoTIFF with a fresh one-hour url, its bands, dtype, scales and offsets.

Array<object>

object

key

additional properties

any

items_used

Scenes that contributed pixels.

Array<string>

error

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

links

required

Self, and result links to the files when done.

Array<object>

A STAC and OGC API link object.

object

href

required

Link target.

string format: uri

rel

required

Relation type, such as self, root, parent, next, prev, items, queryables, tiles or license.

string

type

Media type of the target.

string

title

Human-readable title.

string

method

HTTP method for the link, GET unless stated. Paging POST /v1/search uses POST.

string

Allowed values: GET POST

body

Request body to send with a POST link, used for the next page of POST /v1/search.

object

key

additional properties

any

merge

When true the client merges body into the previous request body.

boolean

key

additional properties

any

Example

{
  "status": "queued",
  "links": [
    {
      "method": "GET"
    }
  ]
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

The X-API-Key header is missing or the key is unknown, disabled or not on this API’s usage plan.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-key",
  "title": "Invalid or missing credentials",
  "status": 401,
  "detail": "Send a valid key in the X-API-Key header.",
  "instance": "/v1/search",
  "code": "invalid-key",
  "requestId": "c1d2e3f4-0000-4a5b-8c9d-0123456789ab"
}

Headers

WWW-Authenticate

string

Challenge naming the accepted scheme.

Example

ApiKey header="X-API-Key"

404

No resource has this id.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No item S2C_T15TVK_20260714T170911_L2X in collection sentinel-2-l2a.",
  "instance": "/v1/collections/sentinel-2-l2a/items/S2C_T15TVK_20260714T170911_L2X",
  "code": "not-found",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

The key’s rate limit or monthly quota (usage plan satdata-personal) was hit.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key spent 300 of its 300 units in the current minute.",
  "instance": "/v1/process",
  "code": "rate-limited",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 17,
  "limits": {
    "unitsPerMinute": 300,
    "unitsSpentThisMinute": 300
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

500

An unexpected server error. No units are charged.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The request failed on our side and was logged. No units were charged.",
  "instance": "/v1/process",
  "code": "internal",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D