# Create a run

> Start Cosmos Agent on a task.

`POST https://api.agent.clatterlabs.xyz/v1/runs` (key permission: `runs: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.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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

- `input` (string, required): What Cosmos should do, in plain language. Up to 20,000 characters.
- `title` (string): A short name for the run (up to 80 characters). Defaults to the first line of `input`.
- `tier` (enum<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). Options: auto, flash, max, heavy.
- `metadata` (object): Your own key/value data, up to 2 KB. Returned as-is on the run.

## Response

- `id` (string): The run id (UUID).
- `object` (string): Always `run`.
- `status` (enum<string>): `queued`, `running`, `completed`, `failed` or `cancelled`.
- `title` (string): The run's title.
- `input` (string): Your instructions (first 4,000 characters).
- `output` (string | null): Cosmos's final answer once `completed`, otherwise `null`.
- `error` (object | null): When `failed`: `{ code, message }`, code `out_of_credits` or `run_failed`.
- `files` (object[]): Files the run saved as outputs: `{ name, bytes }`, plus `content` with `?include=files`.
- `steps` (integer): How many steps the agent took.
- `tier` (string): The tier you asked for: `auto`, `flash`, `max` or `heavy`.
- `usage` (object): `{ tokens }` used by the run.
- `metadata` (object | null): Your `metadata`, returned as-is.
- `key_id` (string): The API key that created the run.
- `created_at / updated_at` (string): ISO 8601 timestamps.

## Example request

```bash
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"
    }
  }'
```

## Example response

```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"
}
```

<Tip>
Write `input` like a ticket: the goal, the limits, and what "done" looks like. See [Your first real run](/agent/first-run).
</Tip>