# Read channel history

`GET /api/channels/{channel}/history`

Percent-decode the channel once and validate it using the core channel grammar. Invalid names are refused without rewriting them to another channel. A failed or late read returns HTTP 503.

### Parameters

| Name | Location | Required | Schema |
|---|---|---|---|
| channel | path | yes | `{"type":"string","minLength":1,"maxLength":4096}` |
| limit | query | no | `{"type":"integer","minimum":0,"maximum":9007199254740991,"default":200}` |

**channel:** Channel name or pattern accepted by the core channel grammar. Encode it as one URL path component.


**limit:** Maximum requested messages. Absent or empty uses 200. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.


### Responses

#### HTTP 200

The current snapshot or history page.

Content type: `application/json`.

```json
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Message"
  }
}
```

#### HTTP 302

A valid one-use k query token is exchanged for a dashboard session. The response redirects to the same path without its query. A valid existing cookie takes precedence over k.

`Location`: The requested path without the query string.

`Set-Cookie`: cotal_web_session=<session>; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.

#### HTTP 400

The query or percent-encoded channel name is invalid.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

#### HTTP 401

No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/AuthenticationError"
}
```

Example:

```json
{
  "error": "unauthenticated"
}
```

#### HTTP 403

Origin is checked before session authentication. An origin outside this listener's allowed origins is refused.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/OriginError"
}
```

Example:

```json
{
  "error": "cross-origin"
}
```

#### HTTP 413

These read routes accept no request body. An announced body is refused before it is read; the connection is closed.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

#### HTTP 500

The request failed. The body names the failure; a failed read does not terminate the dashboard.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

#### HTTP 503

The history read failed or did not finish within 8000 ms.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

Authentication and access: HTTP interface of the @cotal-ai/web reference implementation. This description covers seven read operations; it does not establish a separate stable product or Cloud management API. Start the dashboard using the web service preset described in the operator guide. The server defaults to 127.0.0.1:7799; use the host and port configured for your dashboard.

Open the owner-private launch URL once to exchange its k query token for the cotal_web_session cookie. Keep the session on the same host. With the default bind, the permitted browser origins are http://127.0.0.1:<port>, http://localhost:<port> and http://cotal.localhost:<port>. A custom host uses its own HTTP origin. A cross-origin request is refused before session checks. The readiness nonce only opens /api/meta.

All documented operations use GET and take no request body. Some read handlers also accept other bodyless methods; this description does not promise a 405 response for them. Internal readiness and channel deletion are outside this read reference. The native web service is read-only. Description version 1 identifies this document, not the wire or npm package version.

[OpenAPI specification](https://docs.cotal.ai/dashboard.openapi.json) contains the referenced response schemas. [Complete Markdown reference](/api/dashboard.md).