Cancel Backtest Job

Cancel a queued or running job. Jobs already in a terminal state (done, failed, or cancelled) cannot be cancelled.

Endpoint

POST /v1/backtest/jobs/{id}/cancel

Weight: 5

Authentication: Required (signed)

Path parameters

Name	Type	Mandatory	Description
id	string	Yes	Job identifier returned by Create Job, e.g. bt_3c91ef.

Request body

The body may be empty. An optional reason field is recorded for audit purposes.

Name	Type	Mandatory	Description
reason	string	No	Free-form note (≤ 200 chars) explaining why the job was cancelled.

Response

The job object is returned with status set to cancelled, finished_at populated, and result cleared.

{
  "id": "bt_3c91ef",
  "status": "cancelled",
  "config": {
    "template_id": "tpl_grid",
    "params": {
      "grid_levels": 8,
      "upper_price": "72000",
      "lower_price": "60000"
    },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-12-31T23:59:59Z",
    "capital": "10000.00",
    "leverage": 1,
    "fee_model": "fixed_bps",
    "fee_bps": "5"
  },
  "submitted_at": "2026-04-29T10:15:00Z",
  "started_at": "2026-04-29T10:15:08Z",
  "finished_at": "2026-04-29T10:16:02Z",
  "progress": 0.34,
  "result": null,
  "error": null
}

Response fields

Field	Type	Description
id	string	Job identifier.
status	enum	Always cancelled on a successful cancel.
config	object	Echoed configuration.
submitted_at	string (ISO 8601)	When the job was accepted.
started_at	string (ISO 8601) | null	When the worker began processing. null if cancelled before it ever started.
finished_at	string (ISO 8601)	Set to the cancellation time.
progress	number	Last observed progress at the moment of cancellation.
result	object | null	Always null for cancelled jobs.
error	object | null	Always null; cancellation is not an error.

Errors

HTTP	Code	Cause
404	NOT_FOUND	The job ID does not exist or is not owned by the authenticated key.
409	INVALID_STATE	The job is already in a terminal state (done, failed, or cancelled).

See Errors for shared error semantics.

Example

curl -X POST https://api.pipai.example/v1/backtest/jobs/bt_3c91ef/cancel \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"reason":"superseded by tpl_grid_v2 sweep"}'