> ## Documentation Index > Fetch the complete documentation index at: https://docs.cassidyai.com/llms.txt > Use this file to discover all available pages before exploring further. # List chats > Lists Agent chats started in the range, newest first. **Each chat includes** - Its name and most recent Agent - The person who started it - Where it happened (`source`), such as `web`, `slack`, `teams`, or `embedded` - When it started and when it was last active - The credits it used Filter by person, Agent, model, or source. Agent and model filters match the chat's most recent Agent, so a chat that switched Agents is listed under the one it uses now. Page through results with `cursor`. Excludes chats run by Workflows and Agent test chats. Messages are not included. Requires the Chats permission (`chats:read`). ## OpenAPI ````yaml /admin-api-openapi.json get /chats openapi: 3.1.1 info: title: Cassidy Admin API description: Read your organization's usage analytics and activity in Cassidy. version: 1.0.0 servers: - url: https://app.cassidyai.com/api/admin/v1 security: [] tags: - name: Analytics - name: Workflow runs - name: Chats - name: Meetings - name: Audit logs externalDocs: url: https://docs.cassidyai.com/reference/admin-api paths: /chats: get: tags: - Chats summary: List chats description: >- Lists Agent chats started in the range, newest first. **Each chat includes** - Its name and most recent Agent - The person who started it - Where it happened (`source`), such as `web`, `slack`, `teams`, or `embedded` - When it started and when it was last active - The credits it used Filter by person, Agent, model, or source. Agent and model filters match the chat's most recent Agent, so a chat that switched Agents is listed under the one it uses now. Page through results with `cursor`. Excludes chats run by Workflows and Agent test chats. Messages are not included. Requires the Chats permission (`chats:read`). operationId: listChats parameters: - in: query name: from schema: type: string format: date-time description: >- Inclusive start of the range, by creation time, as an ISO 8601 timestamp. required: true description: >- Inclusive start of the range, by creation time, as an ISO 8601 timestamp. - in: query name: to schema: type: string format: date-time description: >- Exclusive end of the range as an ISO 8601 timestamp. The range can span at most 31 days. required: true description: >- Exclusive end of the range as an ISO 8601 timestamp. The range can span at most 31 days. - in: query name: limit schema: description: Maximum number of records to return. default: 100 type: integer minimum: 1 maximum: 1000 description: Maximum number of records to return. - in: query name: cursor schema: description: The `nextCursor` from the previous page. type: string description: The `nextCursor` from the previous page. - in: query name: agentIds schema: description: >- Only include these Agents, using the IDs from the `agent` breakdown or `/chats`. Built-in models combine their thinking levels. Pass several as a comma-separated list. maxItems: 20 type: array items: type: string description: >- Only include these Agents, using the IDs from the `agent` breakdown or `/chats`. Built-in models combine their thinking levels. Pass several as a comma-separated list. - in: query name: excludeAgentIds schema: description: Leave out these Agents. Pass several as a comma-separated list. maxItems: 20 type: array items: type: string description: Leave out these Agents. Pass several as a comma-separated list. - in: query name: modelIds schema: description: >- Only include Agents that use these models, such as `claude-opus-5-5`, including the built-in model's own Agent. Agents count as the model they use today, so changing an Agent's model moves its past usage too. Thinking levels are combined. Pass several as a comma-separated list. maxItems: 20 type: array items: type: string description: >- Only include Agents that use these models, such as `claude-opus-5-5`, including the built-in model's own Agent. Agents count as the model they use today, so changing an Agent's model moves its past usage too. Thinking levels are combined. Pass several as a comma-separated list. - in: query name: excludeModelIds schema: description: >- Leave out Agents that use these models. Pass several as a comma-separated list. maxItems: 20 type: array items: type: string description: >- Leave out Agents that use these models. Pass several as a comma-separated list. - in: query name: userId schema: description: Only list chats started by this user. type: string description: Only list chats started by this user. - in: query name: source schema: description: Only list chats from this source, such as `slack` or `web`. type: string enum: - web - slack - teams - googleChat - embedded - email - api description: Only list chats from this source, such as `slack` or `web`. responses: '200': description: Successful response content: application/json: schema: type: object properties: nextCursor: description: >- Pass as `cursor` to get the next page. Null on the last page. type: - string - 'null' chats: type: array items: type: object properties: id: type: string name: type: string description: The chat's name. agent: anyOf: - type: object properties: id: type: string name: type: string required: - id - name - type: 'null' description: >- The Agent most recently used in the chat, with the same ID as the `agent` analytics breakdown. Agent and model filters match this Agent. Built-in model Agents combine their thinking levels. user: type: object properties: id: type: string name: type: string email: type: - string - 'null' required: - id - name - email description: The user who started the chat. source: type: string enum: - web - slack - teams - googleChat - embedded - email - api createdAt: type: string lastActivityAt: type: string credits: description: Billable credits used by the chat over its lifetime. type: - number - 'null' required: - id - name - agent - user - source - createdAt - lastActivityAt - credits required: - nextCursor - chats '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/error.NOT_FOUND' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - bearerAuth: - chats:read components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Invalid input data code: type: string description: The error code example: BAD_REQUEST issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message required: - message - code title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Authorization not provided code: type: string description: The error code example: UNAUTHORIZED issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message required: - message - code title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] error.FORBIDDEN: type: object properties: message: type: string description: The error message example: Insufficient access code: type: string description: The error code example: FORBIDDEN issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message required: - message - code title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] error.NOT_FOUND: type: object properties: message: type: string description: The error message example: Not found code: type: string description: The error code example: NOT_FOUND issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message required: - message - code title: Not found error (404) description: The error information example: code: NOT_FOUND message: Not found issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message required: - message - code title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: bearerAuth: type: http scheme: bearer description: An Admin API key, starting with `cas_admin_`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.