Skip to content

Monitor a request

As you saw in the previous example, each request to generate an analysis produces a unique requestId for that request. You can use that request ID to monitor or troubleshoot your requests. Let's check the status of those requests from the previous section.

retrieveRequestDetails()

Copy and paste the query below into the API Playground and press the RUN button. Be sure to change the requestId to the id of your Plant Health request.

query {
  retrieveRequestDetails(
    requestId: "[YOUR REQUEST_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      polygonId
      requestId
      serviceType
      endpoint
      status
      message
      startTime
      stopTime
      sentinelStartTime
      sentinelStopTime
      updatedAt
    }
  }
}

The API will return something like this.

{
  "data": {
    "retrieveRequestDetails": {
      "Status": 200,
      "Message": "Success",
      "Result": {
        "polygonId": "[YOUR POLYGON_ID HERE]",
        "requestId": "[YOUR REQUEST_ID HERE]",
        "serviceType": "PlantHealth",
        "endpoint": "processPlantHealth",
        "status": "Success",
        "message": "Successfully handled request.",
        "startTime": "2023-10-19T09:33:39+00:00",
        "stopTime": "2023-10-19T09:33:53+00:00",
        "sentinelStartTime": "2023-10-19T09:33:21+00:00",
        "sentinelStopTime": "2023-10-19T09:33:39+00:00",
        "updatedAt": "2023-10-19T09:33:53.279404+00:00"
      }
    }
  }
}

The Message, and Status values returned show the overall status of the request. The other values provide more detailed information about the request.

  • status - The current status of the request. This value will change multiple times as the request is processed.
  • message - A longer message about the current status of the request.
  • serviceType - The text representation for the service requested.
  • endpoint - This is the API endpoint (mutation) used for the request.
  • startTime - The processing start time of the request.
  • stopTime - The processing completion time of the request.
  • sentinelStartTime - The start time for downloading the raw satellite data.
  • senteinelStopTime - The stop time for downloading the raw satellite data.
  • updatedAt - This time that the entire request finished processing.

The status and messages are described below.

Status Message Description
Submitted Submitted request. The request is in the queue and processing has not started.
SentinelQueue Request currently in queue awaiting sentinel data download. The request requires raw satellite data and is in the queue to retrieve that data.
SentinelConsumer Request currently downloading sentinel data. The necessary raw satellite data is being downloaded.
NonSentinelQueue Request currently in queue awaiting processing. The request has the required satellite data and is in the queue to process the analysis.
NonSentinelConsumer Request currently being processed. The requested analysis is being processed by the Vultus Platform.
Success Successfully handled request. The requested analysis has completed processing.
Error Something went wrong processing your request. Please try again later. There was an error while processing the request.
NoAvailableDate There were no available dates found for your request. There was no raw satellite data available for the dates of the request.

Now, check the status of your other request using the code below. Be sure to change the requestId to the id of your Water Stress request.

query {
  retrieveRequestDetails(
    requestId: "[YOUR REQUEST_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      polygonId
      requestId
      serviceType
      endpoint
      status
      message
      startTime
      stopTime
      sentinelStartTime
      sentinelStopTime
      updatedAt
    }
  }
}

The result should be similar to the result of your other request.

retrieveSatelliteDownload()

You can use this query to find out more about the raw satellite data for a specific polygon. There will be times when you have asked for an analyses and receive few or maybe zero images. There are two reasons for this, weather and revisit rate

Weather is simple to understand. The satellites cannot see through clouds. If the weather is cloudy when the satellite is overhead of your polygon, there will be no satellite data available to provide an analysis.

Revisit rate refers to how often the satellite is overhead of your polygon. The rate depends on where the polygon is located on the surface of the Earth. Polygons closer to the poles have a shorter revisit rates (2-3 days), while those closer to the equator have longer revisit rates (4-7) days.

The retrieveSatelliteDownload() query provides information about the cloudy days, available days, and unavailable days for a polygon, based on the date ranges of your requests. Copy and paste the query below into the API Playground and press the RUN button. Be sure to change the polygonId to the id of your polygon and the start and end datesto those of your requests.

query {
  retrieveSatelliteDownload(
    polygonId: "[YOUR POLYGON_ID GOES HERE]", 
    startDate: "2023-01-01", 
    endDate: "2023-09-30"
  ) 
  {
    Status
    Result {
      amountOfAvailableDates
      amountOfCloudDectedDates
      amountOfUnavailableDates
      amountOfUnknownDates
      frequencyAvailableDates
      frequencyCloudDetectedDates
      frequencySatelliteImages
      availableDates
      cloudDetectedDates
      unavailableDates
      unknownDates
    }
  }
}

The API will return something like this.

{
  "data": {
    "retrieveSatelliteDownload": {
      "Status": 200,
      "Result": {
        "amountOfAvailableDates": 19,
        "amountOfCloudDectedDates": 124,
        "amountOfUnavailableDates": 222,
        "amountOfUnknownDates": 0,
        "frequencyAvailableDates": 0.0521,
        "frequencyCloudDetectedDates": 0.3397,
        "frequencySatelliteImages": 0.3918,
        "availableDates": [
          "2022-02-28",
          "2022-03-07",
          "2022-03-12",
          "2022-03-20",
          "2022-03-25",
          "2022-04-16",
          "2022-04-26",
          "2022-04-29",
          ...
          "2022-10-16"
        ],
        "cloudDetectedDates": [
          "2022-01-01",
          "2022-01-04",
          "2022-01-06",
          "2022-01-09",
          "2022-01-11",
          "2022-01-14",
          "2022-01-16",
          "2022-01-19",
          "2022-01-21",
          "2022-01-24",
          "2022-01-26",
          "2022-01-29",
          ...
          "2022-12-30"
        ],
        "unavailableDates": [
          "2022-01-02",
          "2022-01-03",
          "2022-01-05",
          "2022-01-07",
          "2022-01-08",
          "2022-01-10",
          "2022-01-12",
          "2022-01-13",
          "2022-01-15",
          "2022-01-17",
          ...
          "2022-12-31"
        ],
        "unknownDates": []
      }
    }
  }
}

Note: All possible values for the date arrays are not shown in the results above.

As you can see, there were:

  • 19 days were an analysis is possible (amountOfAvailableDates),
  • 124 days with clouds and analysis is not possible (amountOfCloudDectedDates),
  • 222 days when the satellites were not overhead and analysis is not possible (amountOfUnavailableDates), and
  • 0 days where there was error retrieving the data (amountOfUnknownDates).

Be sure to wait until your request is done processing, or you will have a large number of unknownDates

retrieveRequestsHistory()

This query is used to see the history of all requests for a single polygon within a defined date range. Copy and paste the query below into the API Playground and press the RUN button. Be sure to change the polygonId to the id of your polygon and the dates to reflect the dates of your requests, not the date ranges of your requests.

query {
  retrieveRequestsHistory(
    polygonId: "[YOUR POLYGON_ID GOES HERE]", 
    startDate: "2023-10-18", 
    endDate: "2023-10-20"
  ) 
  {
    Status
    Message
    Result {
      total
      requests {
        polygonId
        requestId
        status
        message
        endpoint
        serviceType
        startTime
        stopTime
        sentinelStartTime
        sentinelStopTime
      }
    }
  }
}

The API will return something like this.

{
  "data": {
    "retrieveRequestsHistory": {
      "Status": 200,
      "Message": "Success",
      "Result": {
        "total": 11,
        "requests": [
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "Success",
            "endpoint": "processVegetationIndices",
            "serviceType": "VegetationIndices",
            "startTime": "2023-10-19T07:30:20+00:00",
            "stopTime": "2023-10-19T07:30:31+00:00",
            "sentinelStartTime": null,
            "sentinelStopTime": null
          },
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "Success",
            "endpoint": "processSoilOrganicCarbon",
            "serviceType": "SoilOrganicCarbon",
            "startTime": "2023-10-19T07:31:13+00:00",
            "stopTime": "2023-10-19T07:32:11+00:00",
            "sentinelStartTime": null,
            "sentinelStopTime": null
          },
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "Success",
            "endpoint": "processSoilOrganicCarbon",
            "serviceType": "SoilOrganicCarbon",
            "startTime": "2023-10-19T07:33:32+00:00",
            "stopTime": "2023-10-19T07:34:12+00:00",
            "sentinelStartTime": null,
            "sentinelStopTime": null
          },
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "Success",
            "endpoint": "processVegetationIndices",
            "serviceType": "VegetationIndices",
            "startTime": "2023-10-19T11:57:41+00:00",
            "stopTime": "2023-10-19T11:57:42+00:00",
            "sentinelStartTime": null,
            "sentinelStopTime": null
          }
        ]
      }
    }
  }
}

retrieveRequestsInProgress()

This query is used to see the status of all in progress requests for a single polygon. Copy and paste the query below into the API Playground and press the RUN button. Be sure to change the polygonId to the id of your polygon.

query {
  retrieveRequestsInProgress(
    polygonId: "[YOUR POLYGON_ID GOES HERE]"
  ) 
  {
    Status
    Message
    Result {
      total
      requests {
        polygonId
        requestId
        status
        message
        endpoint
        serviceType
        startTime
        stopTime
        sentinelStartTime
        sentinelStopTime
      }
    }
  }
}

If there are in progress requests for the polygon, the API will return something like this.

{
  "data": {
    "retrieveRequestsInProgress": {
      "Status": 200,
      "Message": "Success",
      "Result": {
        "total": 2,
        "requests": [
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "SentinelConsumer",
            "message": "Request currently being processed",
            "endpoint": "processVegetationIndices",
            "serviceType": "VegetationIndices",
            "startTime": "2023-10-20T05:57:03+00:00",
            "stopTime": "2023-10-20T05:57:40+00:00",
            "sentinelStartTime": "2023-10-20T05:56:07+00:00",
            "sentinelStopTime": "2023-10-20T05:57:03+00:00",
            "updatedAt": "2023-10-20T05:57:41.022839+00:00"
          },
          {
            "polygonId": "[YOUR POLYGON_ID HERE]",
            "requestId": "[YOUR REQUEST_ID HERE]",
            "status": "SentinelConsumer",
            "message":  "Request currently being processed",
            "endpoint": "processVegetationIndices",
            "serviceType": "VegetationIndices",
            "startTime": "2023-10-20T05:57:03+00:00",
            "stopTime": "2023-10-20T05:57:40+00:00",
            "sentinelStartTime": "2023-10-20T05:56:07+00:00",
            "sentinelStopTime": "2023-10-20T05:57:03+00:00",
            "updatedAt": "2023-10-20T05:57:41.022839+00:00"
          }
        ]
      }
    }
  }
}

If there are no in progress requests, the API will return something like this.

{
  "data": {
    "retrieveRequestsInProgress": {
      "Status": 404,
      "Message": "There were no requests in progress found for the given polygon.",
      "Result": {
        "total": null,
        "requests": null
      }
    }
  }
}

Now that we know the status of our requests, and that there are dates available for analysis, let's retrieve our analyses.