# List plans

Source: https://docs.coderhelm.com/api/reference/plans/list-plans

`GET /api/plans`

Lists the team's plans, newest first, one page at a time. A listed plan has no tasks; get one plan for its tasks.

## Authentication

A team API key: `Authorization: Bearer chk_...`. The key needs the `view` scope. See [Authentication](https://docs.coderhelm.com/api/authentication).

## Parameters

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Plans per page, 1 to 100. Default 20. |
| `cursor` | string | no | `next` from the previous page. |

## Responses

### 200

A page of plans.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next` | string or null | no | Pass as `cursor` to read the next page; null on the last page. |
| `plans` | array of Plan | yes | Plans, newest first. |
| `plans[].chat_id` | string or null | no | The plan chat it came from. |
| `plans[].created_at` | string or null | no | When it was made (RFC 3339). |
| `plans[].description` | string or null | no | More about it, in Markdown. |
| `plans[].destination` | string or null | no | `github` or `jira`: where its tasks become tickets. |
| `plans[].executed_at` | string or null | no | When it started running (RFC 3339). |
| `plans[].executed_by` | string or null | no | Who started it running. |
| `plans[].mcp_servers` | array of string or null | no | MCP servers used while planning. |
| `plans[].plan_id` | string or null | no | The plan's id. |
| `plans[].repo` | string or null | no | The repository its tasks work in, `owner/name`. |
| `plans[].status` | string or null | no | `draft`, `executing` or `completed`. |
| `plans[].task_count` | integer | yes | How many tasks it has. |
| `plans[].title` | string or null | no | What the plan is for. |
| `plans[].tokens_in` | integer or null | no | Input tokens its runs used so far. |
| `plans[].tokens_out` | integer or null | no | Output tokens its runs used so far. |
| `plans[].updated_at` | string or null | no | When it last changed (RFC 3339). |

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### 401

The key is missing, malformed, revoked or expired, or the person who made it left the team.

### 403

The key lacks the scope this endpoint needs (`missing_scope`).

### 429

Over the key's rate limit (`rate_limited`), or, for endpoints that start work, over the team's monthly token limit (`token_limit_reached`).

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After`.

### 500

Something failed on CoderHelm's side. Safe to retry reads.

## Example request

cURL:

```bash
curl -X GET 'https://api.coderhelm.com/api/plans' \
  -H "Authorization: Bearer $CODERHELM_API_KEY"
```

TypeScript:

```ts
const res = await fetch("https://api.coderhelm.com/api/plans", {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CODERHELM_API_KEY}`,
  },
});
if (!res.ok) {
  const { error, code } = await res.json();
  throw new Error(`${res.status} ${code}: ${error}`);
}
const data = await res.json();
```

Python:

```python
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CODERHELM_API_KEY']}",
}
res = requests.request("GET", "https://api.coderhelm.com/api/plans", headers=headers)
if not res.ok:
    raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")
data = res.json()
```

## Example response

```json
{
  "next": "PLAN#01JB8V0K3M5P7R9T1W3Y5A7C9E",
  "plans": [
    {
      "chat_id": "01JB8TZ6C8E0G2J4L6N8Q0S2U4",
      "created_at": "2026-10-22T13:40:00+00:00",
      "description": "Brute-force attempts are showing up in the auth logs.",
      "destination": "github",
      "executed_at": "2026-10-22T13:55:00+00:00",
      "executed_by": "octocat",
      "mcp_servers": [
        "docs-search"
      ],
      "plan_id": "01JB8V0K3M5P7R9T1W3Y5A7C9E",
      "repo": "acme/web",
      "status": "draft",
      "task_count": 3,
      "title": "Rate-limit the login form",
      "tokens_in": 412300,
      "tokens_out": 38120,
      "updated_at": "2026-10-22T13:55:00+00:00"
    }
  ]
}
```