Getting Started

Monitor a Request

After submitting an analysis request, use monitoring queries to track its progress through the processing pipeline and know when results are ready.

Monitoring Queries

The API provides four queries for monitoring request status:

1. retrieveRequestDetails

Get the status of a specific request by its ID.

GraphQL Query

query { retrieveRequestDetails( requestId: "req-xyz-123" ) { requestId status polygonId analysisType startDate endDate createdAt } }

2. retrieveSatelliteDownload

Check satellite data availability for a polygon and date range.

GraphQL Query

query { retrieveSatelliteDownload( polygonId: "abc123-def456-ghi789" startDate: "2025-06-01" endDate: "2025-08-31" ) { date classification satellite } }

3. retrieveRequestsHistory

View all completed and failed requests for a polygon within a date range.

GraphQL Query

query { retrieveRequestsHistory( polygonId: "abc123-def456-ghi789" startDate: "2025-06-01" endDate: "2025-08-31" ) { requestId status analysisType createdAt } }

4. retrieveRequestsInProgress

List all active requests for a polygon that are still being processed.

GraphQL Query

query { retrieveRequestsInProgress( polygonId: "abc123-def456-ghi789" ) { requestId status analysisType createdAt } }

Status Workflow

Each request progresses through a series of statuses as it moves through the processing pipeline:

Status	Description
`Submitted`	Request has been received and is queued for processing.
`SentinelQueue`	Request is waiting in the Sentinel satellite data download queue.
`SentinelConsumer`	Sentinel satellite data is being downloaded for the polygon.
`NonSentinelQueue`	Request is waiting for additional (non-Sentinel) data processing.
`NonSentinelConsumer`	Additional data sources are being processed.
`Success`	Analysis completed successfully. Results are ready to retrieve.
`Error`	An error occurred during processing. Check the error message for details.
`NoAvailableDate`	No satellite data was available for the requested polygon and date range (typically due to cloud cover).

Tip: Poll the retrieveRequestDetails query periodically until the status reaches Success, Error, or NoAvailableDate. A reasonable polling interval is every 30–60 seconds.

Satellite Download Response

The retrieveSatelliteDownload query returns information about which dates have satellite imagery available. Each entry includes:

date — The date of the satellite pass.
classification — Whether the image is usable: Available, Cloud Detected, Unavailable, or Unknown.
satellite — Which satellite captured the data (e.g., Sentinel-2A, Sentinel-2B).