# Quickstart

> Create an API key and start your first Cosmos Agent run in about five minutes.

This guide takes you from nothing to a finished agent run: Cosmos writes a small program on its cloud computer, runs it, and tells you the result.

## Before you start

You need a **Clatter Labs account**. If you don't have one, create it at [accounts.clatterlabs.com](https://accounts.clatterlabs.com). The Agent API works on every plan, Free included; runs are paid from credits ([Plans and credits](/billing/credits)).

<Steps>
<Step title="Open the Console and copy your Account ID">
Sign in to the [Console](https://console.clatterlabs.com) with your Clatter Labs account. Your **Account ID** looks like `CL-7K2M9QXA` and is shown with a copy button on the Home page and in **Settings**. Every API request sends it next to your key.
</Step>
<Step title="Create an API key">
Go to **API keys** › **Create key**. Give it a name, keep the `runs:write` and `runs:read` permissions, and pick a rate limit (30 requests per minute is the default).

The key starts with `clsk_` and is **shown only once**. Copy it now; Clatter Labs stores only a hash of it.

```bash
export CLATTER_API_KEY="clsk_..."          # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX"    # Console › Settings
```
</Step>
<Step title="Start a run">
Send Cosmos your instructions. The API answers `201` right away with the run.

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

```python Python
import os, requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}
run = 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."},
).json()
print(run["id"], run["status"])
```

```javascript JavaScript
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
  "Content-Type": "application/json",
};
const run = 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." }),
}).then((r) => r.json());
console.log(run.id, run.status);
```
</CodeGroup>
</Step>
<Step title="Watch it work">
Stream the run's events. You'll see a `status` event, one `step` per message or tool call, and a final `done` event with the answer.

```bash
curl -N https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
</Step>
<Step title="Get the result">
Fetch the run any time for its output, the files it saved and its token usage.

```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID?include=files" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
</Step>
</Steps>

<Tip>
Every API reference page has a **Try it** button that sends real requests from your browser, so you can explore without writing code.
</Tip>

## Next steps

<CardGroup cols={2}>
<Card title="Your first real run" icon="play" href="/agent/first-run">Write good instructions, choose a tier, and read results.</Card>
<Card title="Streaming events" icon="radio" href="/agent/streaming">Follow runs live and reconnect without losing steps.</Card>
<Card title="Choose a tier" icon="gauge" href="/agent/tiers">When to use Flash, Max or Heavy.</Card>
<Card title="Errors" icon="circle-alert" href="/agent/errors">Every error code and what to do about it.</Card>
</CardGroup>