Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

The POST /v1/runs/:id/cancel endpoint signals the background browser session for a run to stop. If the run has an active execution context in memory, an AbortController signal is raised and the run transitions to "cancelling" — the browser flow exits at the next cancellation checkpoint and the record is finalised asynchronously. If the run is already in a terminal state ("pass" or "fail"), the endpoint returns a 409 error.

​
Authentication

Pass an API key via the X-Api-Key header or a JWT via the Authorization: Bearer <token> header.

​
Path Parameters

​
id
string (UUID)
required
The run ID returned by POST /v1/run.

​
Response — 200 OK

​
ok
true
Indicates the cancellation signal was accepted.
​
id
string (UUID)
The run ID that was cancelled.
​
status
"cancelling"
The run is in the process of being stopped. Subscribe to GET /v1/runs/:id/events/stream or poll GET /v1/runs/:id to confirm the transition to "fail".

​
Error Responses

StatusBodyMeaning
403{ ok: false, error: "forbidden" }Run exists but belongs to a different user
404{ ok: false, error: "not found" }Run does not exist or belongs to a different user
409{ ok: false, error: "run ya finalizó" }Run already reached a terminal state

​
Orphaned Runs After Server Restart

If the Ghostly API server was restarted while a run was in "running" state, the in-memory AbortController for that run no longer exists. In this case, the cancel endpoint force-finalises the run instead:
  1. The run record is updated to status: "fail".
  2. A run_end assist event is appended with { cancelled: true, source: "user", staleAfterRestart: true }.
  3. The event bus emits the run_end and a final status: "fail" event, then closes.
  4. The response body includes an additional stale: true field alongside ok: true and status: "cancelled".
A stale: true response means the run was stuck in "running" since before the last server restart. Its step results may be incomplete. Check the run record and re-queue if needed.

​
Example

curl -X POST https://api.ghostly.dev/v1/runs/d1e2f3a4-0000-4000-8000-112233445566/cancel \
  -H "X-Api-Key: gly_YOUR_API_KEY"
Example successful response: 
{
  "ok": true,
  "id": "d1e2f3a4-0000-4000-8000-112233445566",
  "status": "cancelling"
}
Example response for a stale, orphaned run: 
{
  "ok": true,
  "id": "d1e2f3a4-0000-4000-8000-112233445566",
  "status": "cancelled",
  "stale": true
}
After receiving a cancelling response, the run will eventually settle to "fail" status. A final run_end event with cancelled: true is emitted on the event bus before the stream closes — you can observe this via GET /v1/runs/:id/events/stream.

Build docs developers (and LLMs) love

Get started for freeTalk to us