Cancel a scheduled request

Cancel a single scheduled request with POST /scheduler/requests/{scheduled_request_id}/cancel. Cancellation is final: the request's status becomes CANCELLED, it will not be called, and it cannot be un-cancelled.

Before you start

You need an API key and the scheduled_request_id of the request you want to cancel. The submission response returns one scheduled_request_id per row in scheduled_requests[], and the polling and query endpoints return it too. See the Call Jobs API reference for details.

Cancel the request

The endpoint takes the request id in the path. There is no request body, and the endpoint cancels one request per call.

1. Send the cancel request with your API key:

API_KEY="$API_KEY"
SCHEDULED_REQUEST_ID="8f2a1b3c-4d5e-4f6a-9b8c-7d6e5f4a3b2c"
URL="https://stage-agent-api.evergrovelabs.com/scheduler/requests/${SCHEDULED_REQUEST_ID}/cancel"

curl -X POST "$URL" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

2. Check the response. 204 No Content with an empty body means the request was cancelled successfully.

After a successful cancellation

The request's status becomes CANCELLED and any recommended callback time on it is cleared. The next time you poll GET /scheduler/call-jobs/{call_job_id} or query with POST /scheduler/call-jobs/query, the request shows CANCELLED.

When a scheduled request cannot be cancelled

The API returns 409 Conflict with a detail reason when the request is not cancellable. There are three reasons:

Cancellation by status

ENQUEUED means the request is waiting to start, so it can be cancelled. ACTIVE means a call is in progress, so cancellation is refused. ERROR is also cancellable, unless a retry call is in progress.

ENQUEUED (waiting to start)
   │
   ├── cancel ──▶ 204 ──▶ CANCELLED
   ▼
   call starts
   ▼
ACTIVE (call in progress)
   │
   ├── cancel ──▶ 409 "still calling"
   ▼
   call ends
   ▼
   ┌─────────────────┬──────────────────────┬──────────────────────┐
   ▼                 ▼                      ▼
COMPLETE         DO_NOT_CALL_BACK         ERROR
   │                 │                      │
   │ cancel: 409     │ cancel: 409          ├── cancel ──▶ 204* ──▶ CANCELLED
   │ "already called │ "already called      │
   │  with outcome"  │  with outcome"       └── if a retry call is
   │                 │                          in progress: 409
   │                 │                          "still calling"
   ▼                 ▼
 (final)          (final)

CANCELLED
   │
   └── cancel ──▶ 409 "already cancelled" (the request does not change)

* A retry call in progress still returns 409 "still calling".

Error responses