Skip to main content

Runs

Cancel a run

View as Markdown

Stop a queued or running run.

POSTapi.agent.clatterlabs.xyz/v1/runs/{id}/cancelruns:write

Stops a queued or running run at its next step, along with any sub-agents it started.

Authorizations

Authorizationstringrequired

Your API key as a bearer token: Bearer clsk_.... Create keys in the Console.

X-Clatter-Accountstringrequired

The Account ID that owns the key, like CL-7K2M9QXA. Find it in Console › Settings. A missing value answers 401 missing_account_id; someone else's answers 401 account_mismatch.

Path parameters

idstringrequired

The run id.

Response

200 · application/json

idstring

The run id (UUID).

objectstring

Always run.

statusenum<string>

queued, running, completed, failed or cancelled.

titlestring

The run's title.

inputstring

Your instructions (first 4,000 characters).

outputstring | null

Cosmos's final answer once completed, otherwise null.

errorobject | null

When failed: { code, message }, code out_of_credits or run_failed.

filesobject[]

Files the run saved as outputs: { name, bytes }, plus content with ?include=files.

stepsinteger

How many steps the agent took.

tierstring

The tier you asked for: auto, flash, max or heavy.

usageobject

{ tokens } used by the run.

metadataobject | null

Your metadata, returned as-is.

key_idstring

The API key that created the run.

created_at / updated_atstring

ISO 8601 timestamps.

curl -X POST "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}

r = requests.post("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel", headers=headers)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
};

const res = await fetch("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel", {
  method: "POST",
  headers,
});
console.log(await res.json());

{
  "id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
  "object": "run",
  "status": "cancelled",
  "title": "Hello from the API",
  "input": "Write hello.py that prints the date, run it, and tell me the output.",
  "output": null,
  "error": null,
  "files": [
    {
      "name": "hello.py",
      "bytes": 61
    }
  ],
  "steps": 4,
  "tier": "auto",
  "usage": {
    "tokens": 18342
  },
  "metadata": {
    "ticket": "OPS-112"
  },
  "key_id": "key_7f3a…",
  "created_at": "2026-10-27T18:40:02.114Z",
  "updated_at": "2026-10-27T18:40:31.870Z"
}
{
  "error": {
    "code": "not_found",
    "message": "No run with that id."
  }
}
{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or was revoked."
  }
}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit: this key allows 30 requests per minute."
  }
}

Was this page helpful?

curl -X POST "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}

r = requests.post("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel", headers=headers)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
};

const res = await fetch("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel", {
  method: "POST",
  headers,
});
console.log(await res.json());

{
  "id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
  "object": "run",
  "status": "cancelled",
  "title": "Hello from the API",
  "input": "Write hello.py that prints the date, run it, and tell me the output.",
  "output": null,
  "error": null,
  "files": [
    {
      "name": "hello.py",
      "bytes": 61
    }
  ],
  "steps": 4,
  "tier": "auto",
  "usage": {
    "tokens": 18342
  },
  "metadata": {
    "ticket": "OPS-112"
  },
  "key_id": "key_7f3a…",
  "created_at": "2026-10-27T18:40:02.114Z",
  "updated_at": "2026-10-27T18:40:31.870Z"
}
{
  "error": {
    "code": "not_found",
    "message": "No run with that id."
  }
}
{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or was revoked."
  }
}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit: this key allows 30 requests per minute."
  }
}