Skip to main content
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.mode de la app. Las apps sync esperan hasta un estado terminal (limitado por execution.timeout_seconds de la app); las apps async devuelven un run_id de inmediato.
  • Explícito 0–60: ambos modos se comportan igual y esperan como máximo wait segundos. wait=0 devuelve en cuanto la ejecución está en cola. En una app sync puedes tomar primero el run_id y luego hacer long-poll con Obtener una ejecución wait.
Cuando la respuesta ya alcanza un estado terminal, 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 de input_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

La carga útil va envuelta en 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_id existente.
  • Las ejecuciones fallidas no se facturan. El éxito parcial y la cancelación solo facturan los registros producidos.