# List runs

> Your API runs, newest first.

`GET https://api.agent.clatterlabs.xyz/v1/runs` (key permission: `runs:read`)

Your API runs, newest first.

## 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`.

## Query parameters

- `limit` (integer, default 20): How many runs to return, 1 to 100.
- `before` (string): A `created_at` timestamp: return runs created before it (for paging).

## Response

- `object` (string): Always `list`.
- `data` (Run[]): Runs, newest first. See [Get a run](/api-reference/runs/get) for the fields.
- `has_more` (boolean): `true` when older runs exist. Pass the last run's `created_at` as `before` to get them.

## Example request

```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs?limit=10" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Example response

```json
{
  "object": "list",
  "data": [
    {
      "id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
      "object": "run",
      "status": "completed",
      "title": "Hello from the API",
      "input": "Write hello.py that prints the date, run it, and tell me the output.",
      "output": "I wrote hello.py and ran it. It printed: 2026-10-27 21:40:12",
      "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"
    }
  ],
  "has_more": false
}
```

Only runs started through the Agent API are listed.