Gestiona las tareas cron
Lista, añade, cambia, desactiva y elimina los comandos programados (tareas cron) de una cuenta de hosting a través de la API y sigue su última ejecución.
Esta guía muestra cómo gestionar con la API las tareas cron de una cuenta de hosting. Una tarea cron ejecuta un comando según un horario dentro del contenedor web de un sitio, como el usuario del sitio.
Qué necesitas
Sección titulada «Qué necesitas»- Una clave de API con el scope
crons:readpara listar las tareas cron ycrons:writepara añadirlas, cambiarlas o eliminarlas (scopes). - El id de la cuenta y el id del sitio que ejecuta el comando. Los obtienes con
GET /api/v1/accountsyGET /api/v1/accounts/{account_id}/sites. - Un plan que permita tareas cron. Sin él, añadir una tarea responde
403 plan_feature_disabled.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export ACCOUNT_ID="5a5a5a5a-1111-4222-8333-444455556666"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"
1. Lista las tareas cron
Sección titulada «1. Lista las tareas cron»GET /api/v1/accounts/{id}/crons devuelve todas las tareas cron de la cuenta, con el resultado de su última
ejecución.
curl -fsS "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
"items": [
{
"id": "8d8d8d8d-1111-4222-8333-444455556666",
"account_id": "5a5a5a5a-1111-4222-8333-444455556666",
"site_id": "6b6b6b6b-1111-4222-8333-444455556666",
"schedule": "*/15 * * * *",
"command": "echo hello from cron",
"enabled": true,
"source": "user",
"last_run_at": "2026-11-14T09:45:00Z",
"last_exit": 0
}
],
"sync": { "state": "applied" }
}
last_run_atylast_exitestán vacíos (null) hasta que la tarea se ha ejecutado una vez. Un código de salida distinto de0significa que el comando falló; su salida está en elcron.logdel sitio.sourceesuserpara las tareas que añadiste tú ymigrationpara las que trajo una migración de cPanel.sync.stateindica si el servidor ha aplicado la lista:applied,pendingofailed.
2. Añade una tarea cron
Sección titulada «2. Añade una tarea cron»POST /api/v1/accounts/{id}/crons añade una tarea. site_id, schedule y command son obligatorios;
enabled es true por defecto.
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"site_id": "'"$SITE_ID"'", "schedule": "*/15 * * * *", "command": "echo hello from cron"}'
La respuesta es 201, con la nueva tarea en cron y un job_id: el servidor aplica el cambio como un job, así
que la tarea cron llega al servidor un instante después. Guarda el id de la nueva tarea como CRON_ID para los
pasos siguientes.
scheduleson cinco campos (minuto, hora, día del mes, mes, día de la semana) o uno de@hourly,@daily,@weekly,@monthly,@yearly.@rebootno está soportado. Las horas son UTC.commandes texto imprimible de 1024 bytes como máximo. Un comando se ejecuta durante una hora como máximo.- Una cuenta tiene como máximo 100 tareas cron.
3. Cambia o desactiva una tarea cron
Sección titulada «3. Cambia o desactiva una tarea cron»PATCH /api/v1/crons/{id} cambia cualquiera de schedule, command, site_id y enabled; los miembros que
omitas se quedan como están. Desactivar mantiene la tarea en la lista.
curl -fsS -X PATCH "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": false}'
La respuesta tiene la misma forma que la de una tarea nueva: cron y job_id. Para enviar el cambio solo si
nadie más ha modificado la tarea mientras tanto, usa una cabecera If-Match.
4. Elimina una tarea cron
Sección titulada «4. Elimina una tarea cron»curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
La respuesta es 204, sin cuerpo.
Sigue el cambio en el servidor
Sección titulada «Sigue el cambio en el servidor»Un cambio responde antes de que el servidor lo haya aplicado. Para esperarlo, consulta el job_id con
GET /api/v1/jobs/{id} (scope jobs:read) hasta que su status sea final, o vigila
GET .../crons hasta que sync.state sea applied. Una aplicación fallida aparece
como sync.state: "failed".
Errores
Sección titulada «Errores»| Estado | Código | Qué significa |
|---|---|---|
401 |
invalid_api_key |
La clave falta, ha caducado o se ha revocado. |
403 |
plan_feature_disabled |
El plan de la cuenta no permite tareas cron. |
403 |
La clave no tiene scope crons, o el usuario no puede gestionar esta cuenta. |
|
404 |
La cuenta o la tarea cron no existe o no es visible para ti. | |
409 |
crons_unsupported_agent |
El agente del servidor no ejecuta tareas cron. |
409 |
conflict |
La cuenta ya tiene 100 tareas cron. |
422 |
validation_failed |
El horario o el comando no es válido, o el sitio no es de la cuenta. |
Los errores son problem details: decide según code.
Eventos
Sección titulada «Eventos»Cuando el servidor ha aplicado un cambio, el job termina y se envía un evento job.succeeded (job.failed si
falló); data.object_id es el job_id de la respuesta. Suscríbete a ellos como se describe en
webhooks.
Relacionado
Sección titulada «Relacionado»- Sitios: las tareas cron en el panel.
- Referencia de la API: cada operación
crons, con sus campos. - Convenciones de la API: errores, idempotencia y ETags.
- Autenticación y claves de API: scopes y manejo de las claves.