---
title: "List chats"
method: GET
path: "/api/chats"
tags: ["Chat"]
---

# List chats

`GET /api/chats`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/chats`
- Auth: HTTP bearer

Retrieve a paginated list of chats for the current user or agent.

## Query parameters

- `limit` integer, required
- `offset` integer, required
- `search` string
- `titleOnly` string
- `pinnedOnly` string
- `excludePinned` string

## Response `200`

Successful response

- object
  - `chats` Chat[], required
    - `id` string, required: Unique chat identifier
    - `userId` string, nullable: User who owns this chat (null for agent or detection chats)
    - `agentId` string, nullable: Agent who owns this chat (null for user or detection chats)
    - `detectionId` string, nullable: Detection this chat belongs to (null for user or agent chats)
    - `parentChatId` string, nullable: Parent chat for nested sub-agent chats (null for top-level chats)
    - `organizationId` string, required: Organization this chat belongs to
    - `title` string, nullable, required: Chat title
    - `createdAt` string, date-time, required: When the chat was created
    - `updatedAt` string, date-time, required: When the chat was last updated
    - `experience` 'chat' | 'write-detection', required: The type of chat experience. Default is "chat".
    - `command` 'create-agent' | 'create-detection-agent' | 'create-response-agent' | 'create-skill' | 'hunt-intel' | 'hunt-intel-new' | 'merge-library-update' | 'tune-detection' | 'update-detection-agent' | 'update-response-agent' | 'update-skill' | 'null', nullable: Slash command that started this chat (e.g., create-response-agent). Null for regular chats.
    - `codeDetectionId` string, uuid, nullable: Code detection this chat is bound to, for Code Mode editor/tuning sessions. Null for regular chats.
    - `codeDetectionSessionMode` 'editor' | 'tuning' | 'null', nullable: How this chat relates to its bound code detection: freeform editing or feedback-driven tuning. Detection-bound chats open in the Code Mode layout.
    - `modelAlias` unknown, required
    - `contentFilterFallbackModelAlias` string, nullable: Active content-filter fallback model for this chat. Later turns use this model until the user explicitly selects a model. Chat history returns null when fallback policy or model availability prevents using the stored pin.
    - `triggerId` string, nullable: ID of the trigger that created this chat
    - `triggerName` string, nullable: Name of the trigger
    - `triggerSource` string, nullable: Source of the trigger (e.g., api, manual, jira, cron, slack)
    - `triggerDescription` string, nullable: Description of the trigger
    - `linearOrganizationId` string, nullable: Linear workspace bound to this chat for Agent Session re-entry
    - `linearIssueId` string, nullable: Linear issue used while reserving an API-created Agent Session
    - `linearAgentSessionId` string, nullable: Linear Agent Session bound to this chat for follow-up routing
    - `status` 'queued' | 'running' | 'waiting' | 'done' | 'error' | 'interrupted', required: Chat execution status: queued (created but not yet claimed), running (actively executing), waiting (awaiting user response), done (completed), error (failed), interrupted (stopped by user)
    - `statusMessage` string, nullable: Additional status context, typically error messages for error status or waiting prompt details
    - `result` union: A JSON value (string, number, boolean, null, array, or object)
      - string
      - number
      - boolean
      - JsonValue[]
      - object
    - `structuredOutputSchema` CotoolJsonSchema: A JSON Schema definition with Cotool-specific extensions for structured output presets
      - `type` 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array', required
      - `title` string
      - `description` string
      - `properties` object
      - `items` CotoolJsonSchema (recursive)
      - `minItems` integer
      - `maxItems` integer
      - `required` string[]
      - `enum` string[]
      - `additionalProperties` boolean
      - `x-cotool` object
        - `presetId` 'classification' | 'markdown' | 'templatedReport' | 'toolCallEvidence'
        - `viewerId` string
    - `shareToken` string, uuid, nullable: Share token for this chat (null if not shared)
    - `isPinned` boolean: Whether the chat is pinned by its owner. Pinned chats appear in a dedicated section in the sidebar.
    - `evalScore` number, nullable: LLM judge evaluation score (0-100)
    - `evalExplanation` string, nullable: Explanation for the evaluation score
    - `evalBulletSummary` string[], nullable: Bullet point summary of the evaluation
    - `criticalIssue` object, nullable: Critical external blocker detected by LLM judge evaluation
      - `category` 'authentication' | 'connectivity' | 'missing_data' | 'permission' | 'configuration' | 'service_unavailable' | 'content_filter', required: Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable)
      - `explanation` string, required: One sentence explaining what went wrong
    - `acceptanceCriteriaResults` object[], nullable: Per-criterion acceptance criteria evaluation results from the LLM judge
      - `criterion` string, required: The acceptance criterion being evaluated
      - `met` boolean, required: Whether the agent run satisfied this acceptance criterion
      - `explanation` string, required: Brief explanation of why the criterion was or was not met
  - `totalCount` integer, required
  - `feedbackByEvent` object

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)