Cancel a running or waiting ActionFlows flow execution via the REST API. Includes the request format and response schema.

Cancel Run

Cancel a running or waiting flow execution.

Endpoint

POST /api/runs/{runId}/cancel

Try it

Live requests run from your browser. Open the API Explorer to try every operation from one screen.

post/api/runs/{runId}/cancel

Cancel run

Requests go to the live API from your browser. The docs server never sees this key.

This request can create, change, or cancel real work.

API key

runId *

X-Locale

curl -X POST 'https://api.actionflows.ai/api/runs/{runId}/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Response

Send a request to see the response.

Authentication

Required. See API Reference for authentication details.

Path Parameters

Parameter	Type	Required	Description
`runId`	string	Yes	The unique identifier of the run (must start with `run_`)

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "run_123",
    "status": "CANCELED",
    "canceledAt": "2024-01-01T00:02:00.000Z"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid run ID"
}

This occurs when the run ID doesn't start with run_.

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required"
}

404 Not Found

{
  "success": false,
  "error": "Run not found"
}

429 Too Many Requests

{
  "error": "Too many requests"
}

Example Requests

cURL

curl -X POST https://api.actionflows.ai/api/runs/run_123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const runId = 'run_123';

const response = await fetch(`https://api.actionflows.ai/api/runs/${runId}/cancel`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

if (data.success) {
  console.log('Run canceled:', data.data.id);
  console.log('Status:', data.data.status);
} else {
  console.error('Error:', data.error);
  
  if (response.status === 404) {
    console.error('Run not found');
  }
}

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

run_id = 'run_123'
response = requests.post(
    f'https://api.actionflows.ai/api/runs/{run_id}/cancel',
    headers=headers
)

data = response.json()

if data['success']:
    print(f"Run canceled: {data['data']['id']}")
    print(f"Status: {data['data']['status']}")
else:
    print(f"Error: {data['error']}")
    
    if response.status_code == 404:
        print("Run not found")

Response Fields

Field	Type	Description
`id`	string	Unique run identifier
`status`	string	Updated run status (should be `CANCELED`)
`canceledAt`	string (ISO 8601)	Timestamp when the run was canceled

Notes

Run IDs must start with run_
Only runs in WAITING or EXECUTING status can be canceled
Already completed, failed, or canceled runs cannot be canceled
The cancellation may take a few moments to process
This endpoint is rate-limited per user
Use the Get Run endpoint to verify the cancellation status

Use Cases

Stop long-running flows that are taking too long
Cancel flows that are no longer needed
Stop test runs that are consuming resources
Implement timeout mechanisms in your application

Cancel Run

Try it

On this page