Sync tasks

A sync task is the unit that drives data synchronisation - it can represent a data source (harvested or uploaded), a calculation, or a scenario. The sync tasks service returns a paginated list of sync tasks with their data connections.

Endpoint¶

curl "https://nexus.stellaspark.com/api/v1/sync_tasks/"

Authentication¶

Using a token gives access to more fields in the response. When combined with ?world=<alias>, each data connection is also enriched with subscription details such as record count and time range.

Query parameters¶

Parameter	Mandatory	Default	Description
`dc_id`	No	-	Comma-separated list of data connection IDs, e.g. `dc_id=6,57`
`feature_type`	No	-	Case-insensitive partial match on feature type alias; also narrows the `dataconnections` in the response.
`locale`	Required with search	World locale	Locale for datasource descriptions, e.g. `nl-NL` or `en-IE`.
`private`	No	-	`true` or `false` - filter by privacy. Requires authentication. Only applies to data source tasks.
`search`	No	-	Case-insensitive search across datasource name and description, and calculation name. Requires `locale`.
`task_type`	No	-	Filter by task type: `data_source`, `calculation`, or `scenario`. Requires authentication.
`uploadable`	No	-	`true` or `false` - filter by whether a datasource accepts file uploads.
`world`	No	-	Filter by world alias. Also enriches each data connection with subscription data (`retention_time`, `n_features`, `oldest_time`, `newest_time`).

Pagination¶

Results are paginated. The response contains count, next, previous, and results.

Parameter	Default	Maximum	Description
`page`	1	-	Page number
`page_size`	10	50	Results per page

Example¶

List all public sync tasks with timeseries data connections in the sandbox world:

curl "https://nexus.stellaspark.com/api/v1/sync_tasks/?world=sandbox&feature_type=timeseries&token={web_api_token}"

Response:

{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 7,
            "name": "Klimatologie - Daggegevens meteostations",
            "owner": "Koninklijk Nederlands Meteorologisch Instituut (KNMI)",
            "task_type": "data_source",
            "private": false,
            "status": "success",
            "trigger": "Every day at 12:00 UTC",
            "harvest_last_success": "2026-03-09T12:00:34Z",
            "uploadable": false,
            "file_upload": null,
            "data_source": {
                "description": "Deze databron bevat dagelijkse meteorologische waarnemingen van de KNMI automatische weerstations (AWS) 
                verspreid over Nederland. Het omvat metingen zoals neerslag, referentieverdamping, relatieve luchtvochtigheid, inkomende 
                zonnestraling, maximale en gemiddelde luchttemperatuur, windrichting en windsnelheden. Elke meetreeks is gekoppeld aan 
                het bijbehorende station en bestrijkt zowel recente als historische perioden.",
                "endpoint": "https://www.daggegevens.knmi.nl",
                "ext": "txt"
            },
            "calculation": null,
            "scenario": null,
            "dataconnections": [
                {
                    "dc_id": 6,
                    "name": null,
                    "feature_type": "timeseries",
                    "join_to": {
                        "feature_type": "weather_station",
                        "prop": "id_src",
                        "dc_id": 18,
                        "dtype": "text"
                    },
                    "output_props": [
                    ],
                    "output_params": [
                        "parameter:airtemp_max_deg_c",
                        "parameter:airtemp_mean_deg_c",
                        "parameter:etref_mm_d",
                        "parameter:hum_rel_pct",
                        "parameter:prec_mm_d",
                        "parameter:rad_in_s_j_cm2_d",
                        "parameter:wind_direction_deg",
                        "parameter:wind_speed_max_hour_mean_m_s",
                        "parameter:wind_speed_max_m_s",
                        "parameter:wind_speed_mean_m_s"
                    ],
                    "retention_time": 189216000,
                    "n_features": 98,
                    "oldest_time": "2020-03-11T00:00:00Z",
                    "newest_time": "2026-03-07T00:00:00Z"
                }
            ]
        },
        {
            ... etc ...
        }
    ]
}

Field reference¶

Sync task fields¶

Field	Meaning
`id`	Unique ID of the sync task
`name`	Name of the data source, scenario or calculation task
`owner`	Organization owning or maintaining the data source
`task_type`	Type of sync task: `data_source`, `calculation`, or `scenario`
`private`	Whether the data source is private (`true`) or public (`false`)
`harvest_last_success`	Timestamp when data was last successfully synchronised
`trigger`	Human-readable sync schedule, e.g. `every_day_at_24_00`, `on_demand`, or `on_input_change`
`uploadable`	Whether users can upload files to this data source
`file_upload`	Most recent file upload for this data source, or `null`. See file upload fields below. Only visible when `uploadable` is `true` and user has access.
`data_source`	Nested object describing the underlying data source, see below
`calculation`	Nested object describing the underlying calculation, see below
`scenario`	Nested object describing the scenario, see below
`dataconnections`	List of data connections associated with this sync task (see below)

File upload fields¶

Field	Meaning
`uploader`	Name of the user who uploaded the file
`filename`	Name of the uploaded file
`download_link`	Temporary pre-signed S3 URL to download the file
`upload_date`	Timestamp when the file was uploaded

Data source fields¶

Field	Meaning
`description`	Localized description of the data source
`endpoint`	Base URL Nexus uses to harvest data from
`ext`	Expected file extension, e.g. `csv`, `geojson`, etc.

Calculation fields¶

Field	Meaning
`id`	Unique ID of the calculation
`description`	Description of the calculation
`name`	Name of the calculation
`owner`	Organization owning the calculation

Scenario fields¶

Field	Meaning
`analysis`	Object with the analysis `name` and `description` (localized via `?locale=`)
`user_name`	Full name of the user who created the scenario

Data connection fields¶

Field	Meaning
`dc_id`	Unique ID of the data connection
`name`	Table name of the data connection
`feature_type`	Feature type alias, e.g. `timeseries`, `road`
`join_to`	Object describing the parent data connection this one joins to. All `null` for root connections.
`output_props`	List of property aliases output by this data connection
`output_params`	List of specific property-choice combinations, e.g. `category:motorway`
`retention_time`	Seconds of historical data retained in Nexus (populated when `?world=` is provided)
`n_features`	Number of features in the subscription (populated when `?world=` is provided)
`oldest_time`	Oldest timestamp in the dataset (populated when `?world=` is provided)
`newest_time`	Newest timestamp in the dataset (populated when `?world=` is provided)