Skip to main content
POST
Avvia un’esecuzione
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs Autenticazione: API key obbligatoria (Authorization: Bearer <API Key>). Il body della richiesta è un’istanza del contratto di input dell’app (input_schema dal dettaglio app). La validazione è strict. wait controlla se questa chiamata attende un risultato:
  • Omesso: segui il default execution.mode dell’app. Le app sync attendono uno stato terminale (limitato da execution.timeout_seconds); le app async restituiscono subito un run_id.
  • Esplicito 0–60: entrambi i modi si comportano uguale e attendono al massimo wait secondi. wait=0 ritorna appena la run è in coda. Per un’app sync puoi prendere prima il run_id e poi fare long-poll con Ottieni un’esecuzione wait.
Se la risposta è già in stato terminale, sample_records può includere il primo batch. Scorri il risultato completo con Ottieni record dell’esecuzione. version pinna la run a un release storico (contratto e pricing seguono quella versione). build è per debug dell’autore: pinna uno snapshot di build immutabile (run_kind=test, escluso dalle stats pubbliche, comunque fatturato). version e build sono mutuamente esclusivi. Il gate della run coincide col gate di dettaglio: app invisibili restituiscono 404; app visibili che non accettano run restituiscono 403 (i self-test dell’autore non hanno restrizioni); nuove run pinnate a una versione yanked sono rifiutate (422).

Richiesta

Parametri di percorso

string
obbligatorio
Riferimento app: app_<hex> oppure <namespace>/<app_name>.

Parametri di query

number
Secondi massimi di attesa di uno stato terminale. Ometti per il default della mode app; 0 ritorna subito dopo lo start.Intervallo da 0 a 60.
integer
Numero massimo di record da produrre. La run termina normalmente al raggiungimento del cap. Usalo per controllare costo e durata.Intervallo ≥ 1.
string
predefinito:"api"
Marker di canale. Default api; SDK e MCP impostano i propri valori. Usabile come filtro su lista run e fatturazione.
string
Pinna a una versione specifica. Default: ultima versione.
string
Solo debug autore. Pinna a uno snapshot di build. Mutuamente esclusivo con version.

Body della richiesta

Oggetto JSON conforme a input_schema dell’app. Partenza più sicura: copia una entry da examples nel dettaglio app e modificala.

Esempio di richiesta

Risposta

200 successo

Il payload è wrappato in data. Campi:
string
obbligatorio
ID esecuzione. Usalo per stato, record e cancel.
string
Username del publisher.
string
Nome dell’app.
string
Versione pinnata. null per run di debug.
string
Snapshot di build pinnato da una run di debug. null per run production.
string
production per run normali; test per run di debug dell’autore.
enum
obbligatorio
Stato run. Valori: PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.
object
Echo dell’input. I campi marcati sensitive nel contratto di input sono redatti.
object
Progresso. done / total sono riportati dall’app; status_text è una stringa di stato leggibile dall’app.
string
ID dataset risultato.
boolean
true quando la run è parzialmente riuscita o è stata annullata. I record prodotti restano usabili.
boolean
true mentre l’annullamento è stato richiesto e il run è ancora in fase di chiusura (arresto cooperativo / recupero dei risultati parziali). Sempre false negli stati terminali (normalizzato lato server), quindi i client non devono ricavarlo da state.
string
Canale di avvio.
string
ID task upstream, se presente.
string
Ora di start. Anche ancora per filtri temporali e attribution di fatturazione.
string
Ora di start dell’esecuzione più recente. Re-stampata al retry.
string
Quando un worker ha claimato la run la prima volta. A differenza di started_at non viene mai riscritto al retry: ancora per il tempo in coda: queued = first_started_at - created_at, wall time totale = finished_at - first_started_at. Derivare il tempo in coda da started_at conta i tentativi precedenti come queueing. null solo per run mai claimate.
string
Ora di fine.
object
Metering usage oggettivo: quanto ha fatto la run. Separato dalla fatturazione; è ciò che le evaluation confrontano.
object
Ledger di fatturazione = usage × pricing × regole di billing. events[] elenca ogni evento billable con quantità, prezzo unitario e importo; total è la somma; charged indica se l’addebito è stato applicato. Completo solo dopo uno stato terminale.
object
Oggetto errore in caso di failure (code / category / message / retryable).
object[]
Primo batch di record quando la risposta è già terminale; altrimenti null.
object[]
Warning strutturati, ad esempio billing-qty-missing.

Errori

Le risposte di errore usano {"error": {code, category, message, retryable}}. Vedi Errori.

Librerie client

Note

  • Vocabolario stati: PENDING, QUEUED, RUNNING, SUCCEEDED, PARTIALLY_SUCCEEDED, FAILED, CANCELLED, EXPIRED. Gli ultimi cinque sono terminali.
  • Non avviare una seconda run per lo stesso obiettivo solo perché un wait è andato in timeout. Fai prima poll del run_id esistente.
  • Le run fallite non sono fatturate. Successo parziale e cancel fatturano solo i record prodotti.