Runs & Results
Iniciar una ejecución
Inicia una ejecución de Data App con entradas que satisfacen el contrato de entrada. Opcionalmente espera el resultado.
POST
Iniciar una ejecución
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs
Autenticación: se requiere API key (Authorization: Bearer <API Key>).
El cuerpo de la solicitud es una instancia del contrato de entrada de la app (input_schema del detalle). La validación es estricta.
wait controla si esta llamada espera un resultado:
- Omitido: sigue el valor por defecto de
execution.modede la app. Las appssyncesperan hasta un estado terminal (limitado porexecution.timeout_secondsde la app); las appsasyncdevuelven unrun_idde inmediato. - Explícito 0–60: ambos modos se comportan igual y esperan como máximo
waitsegundos.wait=0devuelve en cuanto la ejecución está en cola. En una appsyncpuedes tomar primero elrun_idy luego hacer long-poll con Obtener una ejecuciónwait.
sample_records puede incluir el primer lote. Página el resultado completo con Obtener registros de ejecución.
version fija la ejecución a un release histórico (contrato y precios siguen esa versión). build es para depuración del autor: fija un snapshot de build inmutable (run_kind=test, excluido de las estadísticas públicas, igual se factura). version y build son mutuamente excluyentes.
La puerta de ejecución coincide con la de detalle: las apps invisibles devuelven 404; las visibles que no aceptan ejecuciones devuelven 403 (las autopruebas del autor no tienen restricción); las ejecuciones nuevas fijadas a una versión yank se rechazan (422).
Solicitud
Parámetros de ruta
string
requerido
Referencia de app:
app_<hex> o <namespace>/<app_name>.Parámetros de consulta
number
Segundos máximos de espera de un estado terminal. Omite para usar el valor por defecto del modo de la app;
0 devuelve de inmediato tras el inicio.Rango 0 a 60.integer
Máximo de registros a producir. La ejecución termina con normalidad al alcanzar el tope. Úsalo para controlar coste y duración.Rango ≥ 1.
string
predeterminado:"api"
Marcador de canal. Por defecto
api; los SDK y MCP ponen sus propios valores. Sirve de filtro en el listado de ejecuciones y en facturación.string
Fijar a una versión concreta. Por defecto la última versión.
string
Solo debug del autor. Fijar a un snapshot de build. Mutuamente excluyente con
version.Cuerpo de la solicitud
Objeto JSON con la forma deinput_schema de la app. Lo más seguro es copiar una entrada de examples del detalle de la app y editarla.
Ejemplo de solicitud
Respuesta
200 correcto
data. Campos:
string
requerido
Id de la ejecución. Úsalo para estado, registros y cancelación.
string
Nombre de usuario del publicador.
string
Nombre de la app.
string
Versión fijada.
null en ejecuciones de debug.string
Snapshot de build fijado por una ejecución de debug.
null en ejecuciones de producción.string
production para ejecuciones normales; test para debug del autor.enum
requerido
Estado de la ejecución. Valores:
PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.object
Eco de la entrada. Los campos marcados
sensitive en el contrato de entrada se redactan.object
Progreso.
done / total los reporta la app; status_text es un texto de estado legible de la app.string
Result dataset id.
boolean
true cuando la ejecución tuvo éxito parcial o se canceló. Los registros producidos siguen siendo usables.boolean
true mientras se ha solicitado la cancelación y la ejecución aún se está deteniendo (parada cooperativa / recuperación de resultado parcial). Siempre false en estados terminales (normalizado en el servidor), así que los clientes no necesitan derivarlo de state.string
Start channel.
string
Id de la tarea upstream, si está presente.
string
Hora de inicio. También el ancla de filtros por rango temporal y de atribución de facturación.
string
Most recent execution start time. Re-stamped on retry.
string
Cuando un worker reclamó la ejecución por primera vez. A diferencia de
started_at, no se reescribe en reintentos, así que es el ancla del tiempo en cola: en cola = first_started_at - created_at, y tiempo total de pared = finished_at - first_started_at. Derivar el tiempo en cola de started_at cuenta intentos anteriores como cola. null solo en ejecuciones nunca reclamadas.string
End time.
object
Medición objetiva de uso: cuánto hizo la ejecución. Separada de la facturación; es lo que comparan las evaluaciones.
object
Libro de facturación = uso × precios × reglas de facturación.
events[] lista cada evento facturable con cantidad, precio unitario e importe; total es la suma; charged indica si se aplicó el cargo. Completo solo tras un estado terminal.object
Objeto de error en fallo (
code / category / message / retryable).object[]
Primer lote de registros cuando la respuesta ya es terminal; si no,
null.object[]
Advertencias estructuradas, por ejemplo
billing-qty-missing.Errores
Las respuestas de error usan
{"error": {code, category, message, retryable}}. Véase Errores.
Bibliotecas cliente
Notas
- Vocabulario de estados:
PENDING,QUEUED,RUNNING,SUCCEEDED,PARTIALLY_SUCCEEDED,FAILED,CANCELLED,EXPIRED. Los cinco últimos son terminales. - No inicies una segunda ejecución para el mismo objetivo solo porque un wait agotó el tiempo. Primero sondea el
run_idexistente. - Las ejecuciones fallidas no se facturan. El éxito parcial y la cancelación solo facturan los registros producidos.