Runs & Results
Run starten
Data-App-Run mit Inputs starten, die dem Input-Vertrag genügen. Optional auf das Ergebnis warten.
POST
Run starten
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs
Authentifizierung: API-Schlüssel erforderlich (Authorization: Bearer <API Key>).
Der Request-Body ist eine Instanz des App-Input-Vertrags (input_schema aus dem App-Detail). Validierung ist strikt.
wait steuert, ob dieser Aufruf auf ein Ergebnis wartet:
- Weggelassen: dem App-Default
execution.modefolgen.sync-Apps warten bis zu einem terminalen Status (gedeckelt durchexecution.timeout_seconds);async-Apps geben sofort einerun_idzurück. - Explizit 0–60: beide Modi verhalten sich gleich und warten höchstens
waitSekunden.wait=0kehrt zurück, sobald der Run gequeued ist. Bei einersync-App können Sie zuerst dierun_idnehmen und dann mit Run abrufenwaitlong-pollen.
sample_records den ersten Batch enthalten. Das volle Ergebnis seitenweise mit Run-Datensätze abrufen lesen.
version pinnt den Run auf ein historisches Release (Vertrag und Preise folgen dieser Version). build ist für Autor-Debugging: pinnt einen immutable Build-Snapshot (run_kind=test, aus öffentlichen Stats ausgeschlossen, weiterhin billable). version und build schließen sich gegenseitig aus.
Das Run-Gate entspricht dem Detail-Gate: unsichtbare Apps liefern 404; sichtbare Apps, die keine Runs annehmen, liefern 403 (Autor-Selbsttests uneingeschränkt); neue Runs auf eine geyankte Version werden abgelehnt (422).
Anfrage
Pfadparameter
string
erforderlich
App-Referenz:
app_<hex> oder <namespace>/<app_name>.Abfrageparameter
number
Maximale Sekunden bis zu einem terminalen Status. Weglassen für App-Mode-Default;
0 kehrt sofort nach Start zurück.Bereich 0 bis 60.integer
Maximale Anzahl zu erzeugender Datensätze. Der Run endet normal, wenn das Cap erreicht ist. Zur Kosten- und Dauersteuerung.Bereich ≥ 1.
string
Standard:"api"
Kanalmarker. Standard
api; SDKs und MCP setzen eigene Werte. Als Filter in Run-Liste und Abrechnung nutzbar.string
Auf eine bestimmte Version pinnen. Standard: neueste Version.
string
Nur Autor-Debug. Auf einen Build-Snapshot pinnen. Gegenseitig exklusiv mit
version.Anfrage-Body
JSON-Objekt gemäß App-input_schema. Sicherster Start: einen Eintrag aus examples im App-Detail kopieren und anpassen.
Beispielanfrage
Antwort
200 Erfolg
data gewrappt. Felder:
string
erforderlich
Run-ID. Für Status, Datensätze und Abbruch verwenden.
string
Publisher-Benutzername.
string
App-Name.
string
Gepinnte Version.
null bei Debug-Runs.string
Vom Debug-Run gepinnter Build-Snapshot.
null bei Production-Runs.string
production für normale Runs; test für Autor-Debug-Runs.enum
erforderlich
Run-Status. Werte:
PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.object
Input-Echo. Im Input-Vertrag als
sensitive markierte Felder sind redacted.object
Fortschritt.
done / total meldet die App; status_text ist ein menschenlesbarer Statusstring der App.string
Ergebnis-Dataset-ID.
boolean
true, wenn der Run teilweise erfolgreich war oder abgebrochen wurde. Erzeugte Datensätze bleiben nutzbar.boolean
true, solange ein Abbruch angefordert wurde und der Run noch ausläuft (kooperativer Stopp / Wiederherstellung von Teilergebnissen). In Endzuständen immer false (serverseitig normalisiert), sodass Clients es nicht aus state ableiten müssen.string
Startkanal.
string
Upstream-Task-ID, falls vorhanden.
string
Startzeit. Auch Anker für Zeitfilter und Abrechnungszuordnung.
string
Zeit des letzten Ausführungsstarts. Bei Retry neu gestempelt.
string
Wann ein Worker den Run zuerst geclaimed hat. Anders als
started_at wird dies bei Retry nie überschrieben — Anker für Queue-Zeit: queued = first_started_at - created_at, Gesamtwandzeit = finished_at - first_started_at. Queue-Zeit aus started_at abzuleiten zählt frühere Attempts als Queuing. null nur bei nie geclaimten Runs.string
Endzeit.
object
Objektives Usage-Metering: wie viel der Run geleistet hat. Getrennt von der Abrechnung; das vergleichen Evaluations.
object
Abrechnungs-Ledger = Usage × Pricing × Billing-Regeln.
events[] listet jedes billable Event mit Menge, Stückpreis und Betrag; total ist die Summe; charged gibt an, ob die Belastung angewendet wurde. Vollständig erst nach einem terminalen Status.object
Fehlerobjekt bei Failure (
code / category / message / retryable).object[]
Erster Datensatz-Batch, wenn die Antwort bereits terminal ist; sonst
null.object[]
Strukturierte Warnings, z. B.
billing-qty-missing.Fehler
Fehlerantworten nutzen
{"error": {code, category, message, retryable}}. Siehe Fehler.
Client-Bibliotheken
Hinweise
- Status-Vokabular:
PENDING,QUEUED,RUNNING,SUCCEEDED,PARTIALLY_SUCCEEDED,FAILED,CANCELLED,EXPIRED. Die letzten fünf sind terminal. - Starten Sie keinen zweiten Run für dasselbe Ziel nur weil ein Wait getimed out ist. Zuerst die bestehende
run_idpollen. - Fehlgeschlagene Runs werden nicht abgerechnet. Teilerfolg und Cancel billen nur erzeugte Datensätze.