Saltar al contenido
Documentación para desarrolladoresReferencia de la APITrabajos

Consultar un trabajo

Estado, progreso, resumen y coste de un trabajo.

GEThttps://runner.cargoduo.com/v1/jobs/{id}

Consúltalo cada 1–2 s hasta que status sea succeeded, failed o canceled.

Autenticación

Clave de API Bearer con el permisojobs:readMás información

Parámetros de ruta

NombreTipoObligatorioDescripción
idstringobligatorio
string
Sí

ID del trabajo (job_…).

Parámetros de consulta

NombreTipoObligatorioDescripción
includestring
string
No

result incluye el plan de carga en la respuesta cuando el trabajo se ha completado.

result

Ejemplo de solicitud

curl -X GET "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f" \
  -H "Authorization: Bearer $CARGODUO_API_KEY"

Ejemplo de respuesta

200 OK · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "succeeded",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": "2026-10-19T09:12:03Z",
  "finished_at": "2026-10-19T09:12:07Z",
  "progress": {
    "stage": "done",
    "vehicles_done": 1,
    "placed_items": 58
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 58,
    "items_unplaced": 0,
    "vehicles_used": 1,
    "total_weight": 8580,
    "volume_utilization": 0.3116,
    "queue_ms": 12,
    "compute_ms": 4210
  },
  "cost": {
    "credits": 0.28105,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0.06,
      "vehicles": 0.2,
      "compute": 0.02105,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "https://app.cargoduo.com/r/Xq7Lm2Vt9KbR4cN8wZp1Hs6Yd3Fg5Jk0Ta2Ue7Wn4Ci",
  "expires_at": "2026-11-02T09:12:03Z"
}

Respuestas

  • 200OKEl trabajo.
    NombreTipoObligatorioDescripción
    idstringobligatorio
    string
    Sí

    ID del trabajo (job_…).

    objectstringobligatorio
    string
    Sí

    Siempre job.

    job
    statusstringobligatorio
    string
    Sí

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    No

    Tu referencia, tomada de la solicitud.

    sourcestring
    string
    No

    Dónde se creó el trabajo.

    apiplayground
    project_idstring
    string
    No

    El proyecto (prj_…) en el que un trabajo de POST /v1/projects/{id}/pack guarda su plan. Ausente en los demás trabajos.

    created_atstringobligatorio
    string
    Sí

    Marca de tiempo RFC 3339.

    started_atstring | null
    string | null
    No

    Cuándo empezó el cálculo (RFC 3339) o null.

    finished_atstring | null
    string | null
    No

    Cuándo terminó el trabajo (RFC 3339) o null.

    progressJobProgress
    JobProgress
    No

    Progreso en tiempo real mientras está en cola o en curso.

    summaryJobSummary
    JobSummary
    No

    Recuentos y tiempos.

    costJobCost
    JobCost
    No

    Créditos cobrados (definitivos cuando el trabajo termina) y la reserva retenida mientras se ejecutaba.

    errorJobError | null
    JobError | null
    No

    Por qué falló o se canceló el trabajo; null en otro caso.

    warningsWarning[]
    Warning[]
    No

    Observaciones no bloqueantes sobre la solicitud (también se repiten en el resultado).

    result_urlstring
    string
    No

    Haz una solicitud GET a esta URL para obtener el resultado completo cuando status sea succeeded.

    pdf_urlstring
    string
    No

    Enlace que, abierto en un navegador, genera el plan de carga en PDF (vistas 3D + pasos de carga). Válido hasta expires_at. Vacío tras la caducidad.

    expires_atstring
    string
    No

    Cuándo se eliminan los cuerpos de solicitud y de resultado y el enlace al PDF (RFC 3339). Los metadatos y los cargos del trabajo se conservan.

    resultResult
    Result
    No

    El resultado completo, incluido solo si se pide (?include=result) o si POST /v1/pack?wait= terminó a tiempo.

  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedClave de API ausente, mal formada o desconocida.
    • key_revokedLa clave se ha revocado.
    • key_expiredLa clave ha superado su fecha de caducidad.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedLa IP de origen no está en la lista de IP permitidas de la clave.
    • subscription_inactiveLa organización no tiene ninguna suscripción activa que incluya la API.
    • account_inactiveLa organización está suspendida o no tiene ningún propietario con la cuenta activa.
    • scope_missingA la clave le falta un permiso que requiere este endpoint.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 404Not foundjob_not_found
    • job_not_foundNo hay ningún trabajo con este ID en tu organización.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 429Too many requestsrate_limited
    • rate_limitedDemasiadas solicitudes en el minuto, la hora o el día en curso (por clave o por organización), o más de 60 autenticaciones fallidas por minuto desde tu dirección IP.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 500Internal server errorinternal_error
    • internal_errorAlgo ha fallado por nuestra parte.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 503Service unavailableapi_disabled
    • api_disabledLa API está desactivada temporalmente (mantenimiento) o deshabilitada para la organización.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error