> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List agent runs/chats

> Retrieve a paginated list of runs/chats associated with a specific agent.



## OpenAPI

````yaml https://app.cotool.ai/api/docs/openapi.json get /api/agents/{agentId}/chats
openapi: 3.1.0
info:
  title: Cotool API
  version: 1.0.0
  description: >-
    The Cotool REST API. Authenticate with an API key from `/settings/api-keys`
    sent as `Authorization: Bearer <key>`.


    Authentication, error formats, pagination, and common integration recipes
    are documented in the [API
    overview](https://docs.cotool.ai/api-reference/introduction). Endpoints
    marked **Deprecated** keep working; each one's description names its
    replacement.
servers:
  - url: https://app.cotool.ai
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Create, update, run, and version agents.
  - name: Agent Runs
    description: Inspect agent runs, submit feedback, and read evaluation metrics.
  - name: Agent Triggers
    description: Webhook, schedule, and integration triggers that start agent runs.
  - name: Agents as Code
    description: Validate agents and skills defined as YAML in a Git repository.
  - name: Skills
    description: Reusable instructions and tool grants attached to agents.
  - name: Chat
    description: Chat sessions and their transcripts.
  - name: Alerts
    description: Alert triage, routing, and escalation notifications.
  - name: Output Destinations
    description: Webhook, Slack, Jira, and Linear destinations for agent output.
  - name: Detections
    description: Detection agents, detection hits, and the Cotool detection library.
  - name: Hunt
    description: Autonomous hunt threats, gaps, and settings.
  - name: Intel
    description: Threat-intelligence feed items, indicators, and sources.
  - name: Threat Model
    description: The organization threat model and its version history.
  - name: MITRE Coverage
    description: MITRE ATT&CK coverage across detections.
  - name: Tools
    description: Connected tool integrations and captured tool output.
  - name: CLIs
    description: Connected CLI integrations.
  - name: Artifacts
    description: Files and reports produced by agent runs.
  - name: Audit Logs
    description: Organization audit log export and event catalog.
  - name: Users
    description: Users, memberships, and the current session.
  - name: Roles
    description: Role-based permissions.
  - name: Organizations
    description: Organization-level metrics.
paths:
  /api/agents/{agentId}/chats:
    get:
      tags:
        - Agent Runs
      summary: List agent runs/chats
      description: >-
        Retrieve a paginated list of runs/chats associated with a specific
        agent.
      parameters:
        - in: path
          name: agentId
          description: Unique identifier of the agent to list chats for
          schema:
            type: string
            format: uuid
            description: Unique identifier of the agent to list chats for
          required: true
        - in: query
          name: limit
          description: 'Maximum number of chats to return (1-100, default: 10)'
          schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
            description: 'Maximum number of chats to return (1-100, default: 10)'
        - in: query
          name: offset
          description: 'Number of chats to skip for pagination (default: 0)'
          schema:
            type: number
            minimum: 0
            default: 0
            description: 'Number of chats to skip for pagination (default: 0)'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  chats:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chat'
                    description: Array of chat objects for this agent
                  totalCount:
                    type: number
                    description: Total number of chats available for pagination
                required:
                  - chats
                  - totalCount
                description: Paginated list of chats with total count for pagination
        '400':
          description: Bad request — input validation failed or the request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized — missing or invalid API key / session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the authenticated user lacks the required permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: shell
          label: cURL
          source: |-
            curl -X GET "https://app.cotool.ai/api/agents/:agentId/chats" \
              -H "Authorization: Bearer YOUR_API_KEY" \
              -H "Content-Type: application/json"
components:
  schemas:
    Chat:
      type: object
      properties:
        id:
          type: string
          description: Unique chat identifier
        userId:
          type:
            - string
            - 'null'
          description: User who owns this chat (null for agent or detection chats)
        agentId:
          type:
            - string
            - 'null'
          description: Agent who owns this chat (null for user or detection chats)
        detectionId:
          type:
            - string
            - 'null'
          description: Detection this chat belongs to (null for user or agent chats)
        parentChatId:
          type:
            - string
            - 'null'
          description: Parent chat for nested sub-agent chats (null for top-level chats)
        organizationId:
          type: string
          description: Organization this chat belongs to
        title:
          type:
            - string
            - 'null'
          description: Chat title
        createdAt:
          type: string
          description: When the chat was created
          format: date-time
          example: '2025-06-17T12:34:56.789Z'
        updatedAt:
          type: string
          description: When the chat was last updated
          format: date-time
          example: '2025-06-17T12:34:56.789Z'
        experience:
          type: string
          enum:
            - chat
            - write-detection
          description: The type of chat experience. Default is "chat".
        detectionPlatform:
          type:
            - string
            - 'null'
          enum:
            - panther
            - sublime
            - scanner
            - datadog
            - splunk
            - sentinelone
            - microsoftsentinel
            - elastic
            - sumologic
            - runreveal
            - null
          description: >-
            The detection platform for write-detection chats (e.g., scanner,
            splunk, panther). Null for regular chats.
        command:
          type:
            - string
            - 'null'
          enum:
            - create-agent
            - create-detection-agent
            - create-response-agent
            - create-skill
            - hunt-intel
            - tune-detection
            - update-detection-agent
            - update-response-agent
            - update-skill
            - null
          description: >-
            Slash command that started this chat (e.g., create-response-agent).
            Null for regular chats.
        codeDetectionId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Code detection this chat is bound to, for Code Mode editor/tuning
            sessions. Null for regular chats.
        codeDetectionSessionMode:
          type:
            - string
            - 'null'
          enum:
            - editor
            - tuning
            - null
          description: >-
            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:
          description: >-
            Model alias used for this chat. Must be a valid model from the
            registry: auto:chat:default, anthropic:chat:sonnet-5,
            anthropic:chat:sonnet-4.6, anthropic:chat:sonnet-4.5,
            anthropic:chat:opus-5, anthropic:chat:opus-4.8,
            anthropic:chat:opus-4.6, anthropic:chat:opus-4.5,
            anthropic:chat:latest-no-reasoning, anthropic:chat:latest,
            anthropic:chat:opus-4.1, anthropic:chat:opus, google:chat:latest,
            openai:chat:gpt-5.6-sol, openai:chat:gpt-5.6-terra,
            openai:chat:gpt-5.6-luna, openai:chat:gpt-5.5, openai:chat:gpt-5.4,
            openai:chat:gpt-5.3-codex, openai:chat:gpt-5.2-codex,
            openai:chat:gpt-5.2, openai:chat:gpt-5.1, openai:chat:gpt-5,
            openai:chat:latest, openai:chat:4o, openai:chat:o3,
            fireworks:chat:glm-5.3, fireworks:chat:glm-5.3-flash,
            fireworks:chat:glm-5.2, fireworks:chat:glm-5.2-fast,
            fireworks:chat:deepseek-v4-pro, fireworks:chat:deepseek-v4-flash,
            fireworks:chat:kimi-k3, fireworks:chat:kimi-k2.7-code,
            fireworks:chat:kimi-k2.6, fireworks:chat:minimax-m3,
            fireworks:chat:qwen3.7-plus
        triggerId:
          type:
            - string
            - 'null'
          description: ID of the trigger that created this chat
        triggerName:
          type:
            - string
            - 'null'
          description: Name of the trigger
        triggerSource:
          type:
            - string
            - 'null'
          description: Source of the trigger (e.g., api, manual, jira, cron, slack)
        triggerDescription:
          type:
            - string
            - 'null'
          description: Description of the trigger
        linearOrganizationId:
          type:
            - string
            - 'null'
          description: Linear workspace bound to this chat for Agent Session re-entry
        linearIssueId:
          type:
            - string
            - 'null'
          description: Linear issue used while reserving an API-created Agent Session
        linearAgentSessionId:
          type:
            - string
            - 'null'
          description: Linear Agent Session bound to this chat for follow-up routing
        status:
          type: string
          enum:
            - queued
            - running
            - waiting
            - done
            - error
            - interrupted
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            Additional status context, typically error messages for error status
            or waiting prompt details
        result:
          oneOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: Structured chat result data that matches the agent schema
        structuredOutputSchema:
          oneOf:
            - $ref: '#/components/schemas/CotoolJsonSchema'
            - type: 'null'
          description: The schema used to generate the structured output result
        shareToken:
          type:
            - string
            - 'null'
          format: uuid
          description: Share token for this chat (null if not shared)
        isPinned:
          type: boolean
          description: >-
            Whether the chat is pinned by its owner. Pinned chats appear in a
            dedicated section in the sidebar.
        evalScore:
          type:
            - number
            - 'null'
          description: LLM judge evaluation score (0-100)
        evalExplanation:
          type:
            - string
            - 'null'
          description: Explanation for the evaluation score
        evalBulletSummary:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Bullet point summary of the evaluation
        criticalIssue:
          type:
            - object
            - 'null'
          properties:
            category:
              type: string
              enum:
                - authentication
                - connectivity
                - missing_data
                - permission
                - configuration
                - service_unavailable
                - content_filter
              description: >-
                Category of the critical issue (see: authentication,
                connectivity, missing_data, permission, configuration,
                service_unavailable)
            explanation:
              type: string
              description: One sentence explaining what went wrong
          required:
            - category
            - explanation
          description: Critical external blocker detected by LLM judge evaluation
        acceptanceCriteriaResults:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              criterion:
                type: string
                description: The acceptance criterion being evaluated
              met:
                type: boolean
                description: Whether the agent run satisfied this acceptance criterion
              explanation:
                type: string
                description: Brief explanation of why the criterion was or was not met
            required:
              - criterion
              - met
              - explanation
          description: >-
            Per-criterion acceptance criteria evaluation results from the LLM
            judge
      required:
        - id
        - organizationId
        - title
        - createdAt
        - updatedAt
        - experience
        - modelAlias
        - status
      description: A chat conversation between a user/agent and the AI system
    ValidationError:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        issues:
          type: array
          description: >-
            Detailed validation issues, present when request or response schema
            validation fails
          items:
            type: object
            additionalProperties: true
      required:
        - error
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
      required:
        - error
    PermissionError:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        missingPerms:
          type: array
          description: Permissions the authenticated user is missing for this operation
          items:
            type: string
      required:
        - error
    JsonValue:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
      description: A JSON value (string, number, boolean, null, array, or object)
    CotoolJsonSchema:
      type: object
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - 'null'
            - object
            - array
        title:
          type: string
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CotoolJsonSchema'
        items:
          $ref: '#/components/schemas/CotoolJsonSchema'
        minItems:
          type: integer
          minimum: 0
        maxItems:
          type: integer
          minimum: 0
        required:
          type: array
          items:
            type: string
        enum:
          type: array
          items:
            type: string
        additionalProperties:
          type: boolean
        x-cotool:
          type: object
          properties:
            presetId:
              type: string
              enum:
                - classification
                - markdown
                - templatedReport
                - toolCallEvidence
            viewerId:
              type: string
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
      required:
        - type
      description: >-
        A JSON Schema definition with Cotool-specific extensions for structured
        output presets
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API Key authentication for programmatic access. Include your API key in
        the Authorization header as: `Bearer your_api_key_here`

````