.. Copyright (C) 2016-2024 SpaceKnow, Inc.

.. _api.tasking:

***********
Tasking API
***********

.. only:: not holygrail

    * URL: https://api.spaceknow.com/tasking

.. only:: holygrail

    * URL: http://api.local/tasking

Get Pipeline Status
===================

**Needed Permissions**: No permissions are required to access this API
endpoint.

.. http:post:: /tasking/get-status

    :<json string pipelineId: required;
    :<json bool getProgress: optional; whether to retrieve progress of the
        pipeline

    **Example request**:

    .. sourcecode:: json

        {
            "pipelineId": "3g4PovfhGxmymQolpgvv"
        }

    **Example request**:

    .. sourcecode:: json

        {
            "pipelineId": "3g4PovfhGxmymQolpgvv",
            "getProgress": true
        }

    :>json string status: status of the pipeline
    :>json int nextTry: recommended delay for next status check in seconds.
        Available only when pipeline status is ``NEW`` or ``PROCESSING``.
    :>json dict progress: progress stage of the pipeline. Only reported for
        pipelines with ``PROCESSING`` status and if ``getProgress`` parameter
        is set to ``true``.
    :>json string progress.message: progress message
    :>json string progress.provider: name of the provider. Optional.
    :>json int progress.step: step of the pipeline. Total number of steps is 6.


    **Example response**:

    .. sourcecode:: json

        {
            "status": "RESOLVED"
        }

    **Example response**:

    .. sourcecode:: json

        {
            "nextTry": 14,
            "status": "PROCESSING",
            "progress": {
                "message": "Downloading data from provider",
                "provider": "Planet",
                "step": 3
            }
        }

**List of pipeline statuses**:

* ``NEW`` - a pipeline is not yet been processed.
* ``PROCESSING`` - a pipeline is being processed.
* ``FAILED`` - an error occurred during pipeline processing.
* ``RESOLVED`` - a successfully resolved pipeline.

**List of possible progress values**:

* ``Unknown`` - returned when no tasks associated with the pipeline were found
* ``Preparing analysis``
* ``Ordering data from provider``
* ``Waiting for provider data to become available``
* ``Downloading data from provider``
* ``Analyzing``
* ``Finalizing analysis``