Skip to content

Usage

All listing endpoints have the parameters limit and offset available for use.

Get product list

Retrieve a list of the products available for tasking.

Request

curl --location --request GET 'https://api.satellogic.com/tasking/products/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "pk": 90,
            "name": "Some product"
        },
    ]
}

Get task list

Retrieve a list of the tasks submitted by the user.

The list can be filtered by project_name and status

Request

curl --location --request GET 'https://api.satellogic.com/tasking/tasks/?limit=100&offset=0' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'
--data-raw '{
    "project_name": "Theme parks"
}'

Response

{
    "count": 9876,
    "next": "https://api.satellogic.com/tasking/tasks/?limit=100&offset=100",
    "previous": null,
    "results": [
        {
            "task_id": 2488,
            "task_name": "Bush Gardens",
            "project_name": "Theme parks",
            "product": 1,
            "start": "2019-10-24T00:00:00Z",
            "end": "2019-10-31T00:00:00Z",
            "priority": 14,
            "client": "Amusement Corp",
            "target": {
                "type": "Point",
                "coordinates": [
                    -120.087111,
                    34.74643,
                    0.0
                ]
            },
            "created_time": "2018-09-12T21:55:06.221076Z",
            "status": "received"
        },
...

Submit new task

Submit a new task by specifying product, point of interest and time period.

Request

curl --location --request POST 'https://api.satellogic.com/tasking/tasks/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001
        ]
    },
    "start": "2020-12-23T00:00:00+03:00",
    "end": "2021-01-12T00:00:00+03:00"
}'

Response

{
    "task_id": 23272,
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "start": "2020-12-22T21:00:00Z",
    "end": "2021-01-11T21:00:00Z",
    "priority": 14,
    "client": "Amusement Corp",
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001,
            0.0
        ]
    },
    "created_time": "2020-12-23T22:13:52.943224Z",
    "status": "received"
}

Submit new task with specific priority and client

Submit a new task as the example above but with a specific priority (for those accounts granted with a priority range) and client (for those accounts allowed to manage multiple clients).

The priority parameter is optional in all cases, meaning that unless the user specifies a priority number in the request, the default priority for the client in use will be taken into account.

In the case of the client parameter, if the account in use has only one client available, there is no need to send it in the request as that will be the only possible option. Alternatively, if the account manages multiple clients, the user should fill the parameter with the desired client. The accounts available clients can be retrieved using the /clients/ endpoint

Request

curl --location --request POST 'https://api.satellogic.com/tasking/tasks/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001
        ]
    },
    "start": "2020-12-23T00:00:00+03:00",
    "end": "2021-01-12T00:00:00+03:00",
    "priority": 14,
    "client": "Theme parks client"
}'

Response

{
    "task_id": 23272,
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "start": "2020-12-22T21:00:00Z",
    "end": "2021-01-11T21:00:00Z",
    "priority": 14,
    "client": "Theme parks client",
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001,
            0.0
        ]
    },
    "created_time": "2020-12-23T22:13:52.943224Z",
    "status": "received"
}

Query task status

Retrieve status and metadata associated with a task.

Request

curl --location --request GET 'https://api.satellogic.com/tasking/tasks/23221/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

Response

{
    "task_id": 23271,
    "task_name": "Eurodisney",
    "project_name": "Theme parks",
    "product": 90,
    "start": "2020-12-22T21:00:00Z",
    "end": "2021-01-11T21:00:00Z",
    "priority": 14,
    "client": "Amusement Corp",
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001,
            0.0
        ]
    },
    "created_time": "2020-12-23T20:41:19.269776Z",
    "status": "received"
}

Get capture list

Retrieve the list of captures associated with a task

Request

curl --location --request GET 'https://api.satellogic.com/tasking/tasks/2522/captures/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

Response

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "capture_id": "abe88c71-45c5-49e2-93a2-0b22e6c5bf69",
            "start": "2021-02-12T13:24:09.749209Z",
            "satellite_name": "newsat13",
            "status": "published"
        },
        {
            "capture_id": "0b1230b7-51eb-4b2b-a672-f40da25a81f4",
            "start": "2021-02-13T13:36:46.797424Z",
            "satellite_name": "newsat18",
            "status": "processing"
        },
        {
            "capture_id": "fcee0909-1746-4d33-b8a6-0108afd62634",
            "start": "2021-02-15T13:31:23.181541Z",
            "satellite_name": "newsat13",
            "status": "queued"
        }
    ]
}

The response will contain an element in results for every capture planned on behalf of the task.

The attributes for each task are the following:

Parameter Type Description
capture_id string Unique identifier for the capture.
start ISO Datetime Datetime indicating when the capture took place
satellite_name string Name of the satellite executing the capture
status string The capture status
fragment_id UUID Unique identifier for the area fragment. Available for AOI tasks only

Cancel a Task

Cancel a submitted task. The task will appear in the task list with Canceledstatus.

Request

curl --location --request PATCH 'https://api.satellogic.com/tasking/tasks/23241/cancel/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

Recurrent tasks

The usual behavior for tasks is to capture the specified amount of captures once.

The expected_age parameter is a way to set recurrence for POI tasks. It is not available for AOI tasks.

When the expected_age parameter is specified, then the max_captures and max_simultaneous_captures parameters apply to each recurrent period.

For example, if expected_age is set to seven days and none of max_captures or max_simultaneous_captures is specified, the planning process will attempt to generate a planned capture every seven days.

If expected_age is set to ten days and max_captures is set to 2, then the planning process will attempt to generate two planned captures every ten days. The distribution of the captures into the ten days interval will be arbitrary, but as an average, the user will receive two captures every ten days.

Notice that a recurrent task is never completed due to amount of captures. Therefore, the recurrence will continue for the survey period. The Task will be considered as completed only when the survey period is finished, despite the number of past captures.

The expected value for expected_age is a timedelta represented as string. The format is %d %H:%M:%S

Here's an example of a recurrent task creation

Request

curl --location --request POST 'https://api.satellogic.com/tasking/tasks/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001
        ]
    },
    "start": "2020-12-23T00:00:00+03:00",
    "end": "2021-01-12T00:00:00+03:00",
    "expected_age": "7 days, 00:00:00"
}'

Response

{
    "task_id": 23272,
    "task_name": "Disney Land",
    "project_name": "Theme parks",
    "product": 90,
    "start": "2020-12-22T21:00:00Z",
    "end": "2021-01-11T21:00:00Z",
    "priority": 14,
    "client": "Amusement Corp",
    "target": {
        "type": "Point",
        "coordinates": [
            72.905273,
            19.023001,
            0.0
        ]
    },
    "created_time": "2020-12-23T22:13:52.943224Z",
    "status": "received",
    "expected_age": "7 days, 00:00:00"
}

Requesting several captures at once

There are two parameters available for this, max_captures and max_simultaneous_captures. max_captures sets how many past captures are needed for the Task to be considered Completed, and max_simultaneous_captures is an extra parameter used to specify how many captures will be planned at the same time. It is an integer greater or equal than max_captures.

When it is not specified, max_simultaneous_captures takes the same value as max_captures, and the planning process will attempt to generate the exact number of captures the Task needs to be considered complete.

If max_simultaneous_captures takes a higher value, then additional captures will be planned, reducing the latency for the users in case some planned captures fail.

For example, if a user creates a task to obtain a single capture, the planning process will generate a single planned capture. However, if the planned capture fails, the user must wait for the capture to be re-planned.

If the user creates a task to obtain a single capture, but the max_simultaneous_captures is set to 3, then the planning process will attempt to plan three captures, despite only one being required to complete the Task. If the first capture fails, another two already planned may fulfill the order faster than waiting for the task re-planning, reducing the latency from the user's point of view.

If no max_captures is specified while creating a task, a default of 1 is used for both max_capture and max_simultaneous_captures.

It is possible that when max_simultaneous_captures is greater than max_captures, more captures than expected are delivered to the final client. This is because some planned captures are delivered before the Task is set to completed. It is a known issue and a possible side effect of setting a high value to max_simultaneous_captures.

Consulting client's configuration

The endpoint /client/ is intended to retrieve the account configuration including the available client(s) with their corresponding tasking priority levels. The priority level of a Task will determine its placement in the capture planning process using an inverted range, the smaller the number, the higher the priority. In that sense:

  • max_priority refers to the highest priority allowed for the client (the smallest number of the range).
  • min_priority refers to the lowest priority allowed for the client (the biggest number of the range).
  • default_priority it should set between max_priority and min_priority and is the one that will be used in case the priority parameter is not sent in the request.

Request

curl --location --request GET 'https://api.satellogic.com/tasking/clients/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

Response

{
  "name": "Amusement Corp",
  "description": "",
  "contact_name": "John Smith",
  "contact_email": "contact@email.com",
  "geofence": None, // or a geojson geometry
  "min_priority": 15,
  "max_priority": 13,
  "default_priority": 14,
  "date_created": "2023-01-01 10:00:00",
  "last_update": "2023-01-02 10:00:00"
}
Last update: 2024-04-11