Scheduled pentests API

HTTP reference for scheduling a completed pentest to re-run once, daily, weekly or monthly, and for listing, rescheduling and cancelling those schedules.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). These endpoints automate the same recurring re-runs described in Scheduled pentests; read that page for the product model (timezones, auto-fill, execution status). The Python SDK mirrors them as client.pentests.scheduled.* — see SDK resources.

Scheduled pentests

GET    /scheduled-pentests
POST   /scheduled-pentests
PUT    /scheduled-pentests/{id}
DELETE /scheduled-pentests/{id}

A schedule binds a completed pentest to a recurrence. Only pentests in the completed state can be scheduled, and a pentest can have just one active schedule at a time. Scheduling moves the pentest into a scheduled state; cancelling reverts it to completed. Availability and limits come from your tier (Pro and up) — see Teams & tiers.

Schedule a pentest

POST /scheduled-pentests

The body identifies the pentest and the recurrence. next_run is never supplied by the client — it is computed server-side from schedule_type, schedule_time and schedule_day in your timezone, then stored in UTC.

{
  "pentest_id": 87,
  "schedule_type": "weekly",
  "schedule_time": "14:30:00",
  "schedule_day": 5
}

Field rules:

• schedule_type — one of once, daily, weekly, monthly.
• schedule_time — HH:MM or HH:MM:SS in your local timezone.
• schedule_day — depends on the type: omit (null) for daily; 1–7 (Monday–Sunday) for weekly; 1–31 (day of month) for monthly; optional for once (defaults to today, but required if the chosen time has already passed today).

The response (201) returns the stored schedule, with next_run and last_run converted back to your timezone:

{
  "success": true,
  "data": {
    "id": 12,
    "pentest_id": 87,
    "pentest": {
      "name": "Acme web assessment",
      "type": "web",
      "url": "https://example.com",
      "assets": [
        {"id": 5, "type": "url", "value": "https://example.com", "is_primary": true}
      ]
    },
    "schedule_type": "weekly",
    "schedule_time": "14:30:00",
    "schedule_day": 5,
    "next_run": "2026-06-26 14:30:00",
    "last_run": null,
    "is_active": true,
    "execution_status": "idle",
    "current_phase": null,
    "progress_percentage": 0,
    "timezone": "Europe/Madrid",
    "created_at": "2026-06-22 09:00:00",
    "updated_at": "2026-06-22 09:00:00"
  }
}

Scheduling a pentest that isn’t completed, or one that already has an active schedule, returns 400.

List schedules

GET /scheduled-pentests

Returns your own schedules plus those of teams you belong to, sorted by next_run. Paginate with page and per_page:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 12,
        "pentest_id": 87,
        "schedule_type": "weekly",
        "schedule_time": "14:30:00",
        "schedule_day": 5,
        "next_run": "2026-06-26 14:30:00",
        "last_run": null,
        "is_active": true,
        "execution_status": "idle",
        "timezone": "Europe/Madrid"
      }
    ],
    "pagination": {"total": 1, "count": 1, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

execution_status tracks a run in flight: idle → running → completed (or failed).

Reschedule

PUT /scheduled-pentests/{id}

Send any subset of schedule_type, schedule_time and schedule_day; at least one is required. next_run is recalculated from the merged values. To move the example to the first of every month at 09:00:

{"schedule_type": "monthly", "schedule_time": "09:00:00", "schedule_day": 1}

The response mirrors the create payload with the updated schedule.

Cancel

DELETE /scheduled-pentests/{id}

Removes the schedule and reverts the pentest to completed, so it stops running automatically.

{
  "success": true,
  "data": {
    "id": 12,
    "pentest_id": 87,
    "status": "cancelled",
    "message": "Schedule cancelled successfully. Pentest status reverted to completed."
  }
}