Process Status

Poll the status of an upload process from the Alphacast Python SDK to know when your data is ready.

When you upload data with upload_data_from_df or upload_data_from_csv, the call returns immediately with a process record. The actual merge runs in the background. Use the methods below to check progress and inspect the result.

For the full upload lifecycle (states, idempotency, notifications) see Upload lifecycle in the Documentation tab.

List all processes for a dataset

processes() returns every upload process recorded for the dataset, most recent first. The response is the raw API body as bytes — decode and parse it as JSON:

import json

raw = alphacast.datasets.dataset(7938).processes()
processes = json.loads(raw)

for p in processes[:5]:
    print(p["id"], p["status"], p.get("statusDescription"))

Each entry includes at least:

Field	Meaning
id	Process ID.
datasetId	The dataset this process belongs to.
status	Requested, Processing, Processed, or Error.
statusDescription	Free-text summary (e.g., 1292 values added to database.).
deleteMissingFromDB	The flag value used for this upload.
onConflictUpdateDB	The flag value used for this upload.
createdAt	When the upload was submitted.
processedAt	When processing finished.

Get a single process

If you saved the process ID returned by the upload call, fetch only that record with process(id):

import json

raw = alphacast.datasets.dataset(7938).process(45141)
record = json.loads(raw)

print(record["status"], record.get("statusDescription"))

The response shape matches a single entry from processes().

Polling pattern

To wait for an upload to complete, poll until the status leaves Requested/Processing:

import json
import time

dataset_id = 7938
upload = alphacast.datasets.dataset(dataset_id).upload_data_from_df(df)
process_id = json.loads(upload)["id"]

while True:
    raw = alphacast.datasets.dataset(dataset_id).process(process_id)
    record = json.loads(raw)
    status = record["status"]

    if status in ("Processed", "Error"):
        break

    time.sleep(5)

if status == "Error":
    raise RuntimeError(f"Upload failed: {record.get('statusDescription')}")

print("Upload complete:", record.get("statusDescription"))

Most uploads finish in seconds. For large CSVs (hundreds of MB) processing can take several minutes — only one process per dataset runs at a time, so subsequent uploads wait in Requested until the in-flight job finishes.

Upload stats

After a successful run, the process record’s stats field contains row-level counts: insertedValues, updatedValues, deletedValues, changedValues, totalValues, minDate, maxDate. Use these for logging or to drive your own monitoring:

record = json.loads(alphacast.datasets.dataset(7938).process(45141))
stats = record.get("stats", {})

print("Inserted:", stats.get("insertedValues"))
print("Updated:", stats.get("updatedValues"))
print("Deleted:", stats.get("deletedValues"))

Error handling

When the worker rejects the upload — duplicated rows, manifest mismatch, missing date column — the process transitions to Error and statusDescription carries the message. The full list of validation rules is documented in Validation rules.

record = json.loads(alphacast.datasets.dataset(7938).process(45141))

if record["status"] == "Error":
    print("Upload failed:", record["statusDescription"])

Next steps

• Trigger a new upload — see Uploading data.
• Read the dataset back once processing finishes — see Downloading data.