Clatter Labs
Console

Runs

Create a run

View as Markdown

Start Cosmos Agent on a task.

POSTapi.agent.clatterlabs.xyz/v1/runsruns:write

Starts Cosmos on its cloud computer with your instructions. Answers 201 right away with the run; follow it with the events stream or poll it.

Write input like a ticket: the goal, the limits, and what "done" looks like. See Your first real run.

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.

Body

application/json

inputstringrequired

What Cosmos should do, in plain language. Up to 20,000 characters.

titlestring

A short name for the run (up to 80 characters). Defaults to the first line of input.

tierenum<string>default: auto

The SuperCosmos tier to run on. auto lets Cosmos route each step; tokens are billed at the tier each call actually runs on (an auto run bills as Flash).

Available options: auto, flash, max, heavy

metadataobject

Your own key/value data, up to 2 KB. Returned as-is on the run.

Response

201 · 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" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Write hello.py that prints the date, run it, and tell me the output.",
    "title": "Hello from the API",
    "tier": "auto",
    "metadata": {
      "ticket": "OPS-112"
    }
  }'
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",
    headers=headers,
    json={
        "input": "Write hello.py that prints the date, run it, and tell me the output.",
        "title": "Hello from the API",
        "tier": "auto",
        "metadata": {
            "ticket": "OPS-112"
        }
    },
)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
  "Content-Type": "application/json",
};

const res = await fetch("https://api.agent.clatterlabs.xyz/v1/runs", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "input": "Write hello.py that prints the date, run it, and tell me the output.",
    "title": "Hello from the API",
    "tier": "auto",
    "metadata": {
      "ticket": "OPS-112"
    }
  }),
});
console.log(await res.json());
{
  "id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
  "object": "run",
  "status": "running",
  "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": [],
  "steps": 0,
  "tier": "auto",
  "usage": {
    "tokens": 0
  },
  "metadata": {
    "ticket": "OPS-112"
  },
  "key_id": "key_7f3a…",
  "created_at": "2026-10-27T18:40:02.114Z",
  "updated_at": "2026-10-27T18:40:02.114Z"
}
{
  "error": {
    "code": "bad_request",
    "message": "`input` is required: say what Cosmos should do."
  }
}
{
  "error": {
    "code": "out_of_credits",
    "message": "You're out of Clatter Labs credits. Add credits in the Console to keep going."
  }
}
{
  "error": {
    "code": "too_many_runs",
    "message": "You already have 5 runs in progress. Wait for one to finish or cancel it."
  }
}