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 endpoint returns a paginated list of sync tasks with their data connections.

Endpoint¶

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

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	Description
`dc_id`	Comma-separated list of data connection IDs, e.g. `dc_id=6,57`
`feature_type`	Case-insensitive partial match on feature type alias; also narrows the `dataconnections` in the response
`locale`	Locale for datasource descriptions, e.g. `nl-NL` or `en-IE`. Defaults to the user's world locale. Required when using `search`.
`private`	`true` or `false` - filter by privacy. Requires authentication. Only applies to data source tasks.
`search`	Case-insensitive search across datasource name, calculation name, and datasource description. Requires `locale`.
`task_type`	Filter by task type: `data_source`, `calculation`, or `scenario`. Requires authentication.
`uploadable`	`true` or `false` - filter by whether a datasource accepts file uploads
`world`	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_new/?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,
            "uploadable": false,
            "trigger": "Every day at 12:00 UTC",
            "harvest_last_success": "2026-03-09T12:00:34Z",
            "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`)
`uploadable`	Whether users can upload files to this data source
`harvest_last_success`	Timestamp when data was last successfully synchronised
`trigger`	Human-readable sync schedule, e.g. `Every day at 12:00`, `On demand`, or `On input change`
`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)

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)

Renaming and deleting scenarios¶

Renaming and deleting a scenario is allowed for:

The user who created the scenario
Coworkers with the Scenario Analyst role from the same organisation as the user who created it

Uploading data¶

For uploadable data source tasks, you can upload a file directly via:

curl -F "upload_file=@/path/to/file.csv" "https://nexus.stellaspark.com/api/v1/sync_tasks_new/{id}/upload/?token={web_api_token}"

Authentication is required. The sync task must have task_type=data_source and uploadable=true. See the Upload service for more details on uploading data.