Skip to content
satellitedata.net

Rendered preview of one item

GET
/v1/collections/{collectionId}/items/{itemId}/preview.{format}
curl --request GET \
  --url 'https://api.satellitedata.net/v1/collections/sentinel-2-l2a/items/S2C_T15TVK_20260712T171233_L2A/preview.png?preset=true-color&max_size=512' \
  --header 'If-None-Match: "r3-9f2c1a"'

Renders one item through a preset, true colour by default, at up to 1,024 pixels on the long edge. The catalog page and search results use it as a thumbnail. Anonymous callers are served from the CloudFront cache or a one-time render; keyed callers pay units only on an origin render. Without a credential, only responses already in the CloudFront cache are served; a miss returns 401 render-requires-credential. A guest token, key or session renders misses and is charged units.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
collectionId
required
string
/^[A-Za-z0-9_.-]+$/

Collection id or alias without a slash, for example sentinel-2-l2a or S2L2A.

Example 

sentinel-2-l2a
itemId
required
string

Native item id.

Example 

S2C_T15TVK_20260712T171233_L2A
format
required
string
Allowed values: png jpg webp

Image format.

Example 

png

Query Parameters

Section titled “Query Parameters”
preset
string
default: true-color

Preset used to render the preview.

Example 

true-color
max_size
integer
default: 512 >= 64 <= 1024

Longest edge of the preview in pixels.

Example 

512

Header Parameters

Section titled “Header Parameters”
If-None-Match
string

ETag from an earlier response; a match returns 304.

Example 

"r3-9f2c1a"

Responses

Section titled “Responses”

200

Section titled “200”

Preview image.

string

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
ETag
string

Entity tag; includes the render version.

Example 
"r3-9f2c1a"
Cache-Control
string

Caching policy for CloudFront and browsers.

Example 
public, max-age=3600, s-maxage=2592000, stale-if-error=604800
X-Units-Spent
number

Units charged for this response; 0 for cache hits and free routes.

Example 
1.333
X-Attribution
string

Credit lines for the data in the response, separated by semicolons.

Example 
Contains modified Copernicus Sentinel data 2026; Landsat data courtesy of the U.S. Geological Survey

304

Section titled “304”

The ETag matches; the cached copy is current.

Headers

Section titled “Headers”
ETag
string

Entity tag; includes the render version.

Example 
"r3-9f2c1a"
Cache-Control
string

Caching policy for CloudFront and browsers.

Example 
public, max-age=3600, s-maxage=2592000, stale-if-error=604800

400

Section titled “400”

The request is malformed or a parameter is invalid.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
key
additional properties
any

Example 

{
  "type": "https://docs.satellitedata.net/problems/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "bbox must have 4 or 6 numbers; got 3.",
  "instance": "/v1/search",
  "code": "invalid-parameter",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "errors": [
    {
      "pointer": "bbox",
      "detail": "expected 4 or 6 numbers"
    }
  ]
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

Section titled “401”

The API key or bearer token is missing, unknown, revoked or expired.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
key
additional properties
any

Example 

{
  "type": "https://docs.satellitedata.net/problems/invalid-key",
  "title": "Invalid or missing credentials",
  "status": 401,
  "detail": "Send a verified key in X-API-Key or a bearer token from /oauth/token.",
  "instance": "/v1/process",
  "code": "invalid-key",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
WWW-Authenticate
string

Challenge naming the accepted schemes.

Example 
Bearer realm="satellitedata.net", ApiKey header="X-API-Key"

404

Section titled “404”

No resource has this id.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
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

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

Section titled “429”

A per-minute, concurrency, monthly or per-IP limit was hit. Retry-After says when to retry.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
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

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
Retry-After
integer

Seconds to wait before retrying.

Example 
17
RateLimit
string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example 
"units";r=287;t=41
RateLimit-Policy
string

Quota policy of the caller (IETF RateLimit header draft).

Example 
"units";q=300;w=60

500

Section titled “500”

An unexpected server error. No units are charged.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
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

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

503

Section titled “503”

An upstream catalog or bucket is unavailable, or the service is in maintenance. No units are charged.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
key
additional properties
any

Example 

{
  "type": "https://docs.satellitedata.net/problems/upstream-unavailable",
  "title": "Upstream unavailable",
  "status": 503,
  "detail": "NASA Earthdata returned 503 for the HLS credentials endpoint; HLS scenes are temporarily unavailable.",
  "instance": "/v1/process",
  "code": "upstream-unavailable",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 120
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
Retry-After
integer

Seconds to wait before retrying.

Example 
17

504

Section titled “504”

The render did not finish within the 29-second API Gateway limit. No units are charged.

Media typeapplication/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
unitsEstimated

Units the request would have cost, computed before execution.

number
error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string
message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string
key
additional properties
any

Example 

{
  "type": "https://docs.satellitedata.net/problems/render-timeout",
  "title": "Render timed out",
  "status": 504,
  "detail": "The render read 41 scenes and did not finish in 29 seconds. Narrow the time range or lower the output size.",
  "instance": "/v1/process",
  "code": "render-timeout",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D