Tasks

Tasks

Associated Terms
Export tasks, Background jobs, Async exports

Contents

• Overview
• Task object structure
• Scheduling and triggers
• Permissions and Authentication
• Endpoints
• Related documentation

Overview

Tasks in Spaaza represent asynchronous background jobs that run on the Services API. The most common use case is exporting data (transactions, users, vouchers, wallet entries, products, and product variants) to CSV or JSON files.

The Services API provides separate hostnames for production and staging environments. Consult your Spaaza contact for the correct hostname for your environment.

A task moves through the following lifecycle:

State	Description
READY	The task has been created and is waiting for its scheduled time.
INPROGRESS	The task is currently running.
DONE	The task completed successfully. The result file is available.
ERROR	The task failed. Check the task logs for details.

The typical workflow for an export task is:

1. Create a task — POST /tasks with export details and a trigger time.
2. Poll status — GET /tasks/{id} until state is DONE or ERROR.
3. Download the result — GET /tasks/{id}/download_url returns a temporary pre-signed URL.

Tasks can also be executed immediately without waiting for the scheduled time by calling POST /tasks/{id}/execute.

Task object structure

All endpoints that return a task use the following JSON structure:

Field	Type	Description
id	integer	Unique task identifier.
chain	integer	Chain ID for which the task was created.
desc	string	Task description (for reference purposes).
state	object	Current task state (see below).
state.code	string	Status code: READY, INPROGRESS, DONE, ERROR.
state.last_run_date	string	ISO 8601 datetime of the last run.
state.last_modified	string	ISO 8601 datetime of the last modification.
state.created_date	string	ISO 8601 datetime when the task was created.
trigger	object	The trigger configuration (see Scheduling and triggers).
target	object	The target configuration (see Target parameters).
logs	array	Task execution log entries (see Log entries).
debug	string	Debug string.
version	integer	Internal version number.
result	string	Result filename (populated when state is DONE).

Target parameters

The target object defines what the task does:

Field	Type	Description
target.action	string	The action to perform. Use "export" for data exports.
target.export_index	string	The data index to export. One of: transactions, users, vouchers, wallet-ledger, products, product-variants.
target.export_format	string	The output format. One of: csv, json.

Log entries

Each entry in the logs array may contain:

Field	Type	Description
msg	string	Log message (e.g. "READY -> INPROGRESS", "success").
time	string	ISO 8601 datetime of the log entry.
total	integer	Total records processed (present on completion).
errors	integer	Number of errors during processing.
skips	integer	Number of skipped records.
success	integer	Number of successfully processed records.

Scheduling and triggers

The trigger object controls when a task runs and what data it operates on:

Field	Type	Required	Description
trigger.once	string	required	ISO 8601 datetime when the task should execute. Set to a time shortly in the future.
trigger.repeat	string	optional	Repeat schedule after initial run. One of: "daily", "weekly", "monthly". If omitted or empty, the task runs once only.
trigger.segment	object	conditional	Inline segment filter rules. See Segment filter reference.
trigger.segment_id	string	conditional	ID of a saved segment (from Console). Alternative to inline segment.

note

Either trigger.segment, trigger.segment_id, or neither can be provided. If neither is provided, all records in the index are exported (unfiltered).

When trigger.repeat is set, the task automatically reschedules itself after each run:

Repeat value	Behaviour
"daily"	After each run, trigger.once is advanced to the next day.
"weekly"	Runs on the same weekday and time, every week.
"monthly"	Runs on the same day-of-month and time, every month.

Permissions and Authentication

All tasks endpoints require chain-scoped authentication on the Services API. See the authentication page for more details on authentication methods. The following authentication types are permitted:

• Privileged authentication: the use of privileged authentication is permitted for all tasks endpoints. This is the recommended method for service-to-service integrations.
• Admin authentication: the use of admin authentication is permitted. The performing user needs to have the appropriate access level for the chain.

Endpoints

Method	Endpoint	Description
POST	/tasks	Create a task
GET	/tasks	List tasks
GET	/tasks/{id}	Get a task
PUT	/tasks/{id}	Update a task
DELETE	/tasks/{id}	Delete a task
GET	/tasks/{id}/download_url	Get download URL
POST	/tasks/{id}/execute	Execute a task

Related documentation

• Exporting data — Use-case guide with worked examples
• Segment filter reference — Operators, field types, and rule syntax