> ## Documentation Index > Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > List chatbot conversations. Required scope: `conversations:read`. On success, `data` contains: `conversations`, `filters`, `pagination`. ## OpenAPI ````yaml https://sitegpt.ai/api/v2/openapi.json get /api/v2/chatbots/{chatbotId}/conversations openapi: 3.1.0 info: title: SiteGPT Agent API version: 2.0.0 description: >- Agent-facing API for managing SiteGPT chatbots, dashboard summaries, appearance media, knowledge, settings, conversations, leads, members, account profiles, usage, billing reads, and API tokens. servers: - url: https://sitegpt.ai security: - bearerAuth: [] tags: - name: Discovery - name: Onboarding - name: Account - name: Billing - name: Tokens - name: Chatbots - name: Knowledge - name: Knowledge Sync Jobs - name: Knowledge Sources - name: Custom Responses - name: Personas - name: Instructions - name: Settings - name: Conversation Starters - name: Conversation Followups - name: Members - name: Leads - name: Conversations - name: Messages - name: Tags paths: /api/v2/chatbots/{chatbotId}/conversations: get: tags: - Conversations summary: List conversations description: |- List chatbot conversations. Required scope: `conversations:read`. On success, `data` contains: `conversations`, `filters`, `pagination`. operationId: listConversations parameters: - name: chatbotId in: path required: true description: Chatbot ID. schema: type: string - name: limit in: query required: false description: Maximum number of records to return. schema: type: integer minimum: 1 - name: cursor in: query required: false description: Pagination cursor. schema: type: string - name: status in: query required: false description: Conversation status filter. schema: type: string enum: - all - open - resolved - name: mode in: query required: false description: Conversation mode filter. schema: type: string enum: - AI - AGENT - name: important in: query required: false description: Important flag filter. schema: type: boolean - name: escalated in: query required: false description: Escalated flag filter. schema: type: boolean - name: read in: query required: false description: Read flag filter. schema: type: boolean - name: leadId in: query required: false description: Lead ID filter. schema: type: string - name: tagId in: query required: false description: Repeatable tag ID filter. schema: type: array items: type: string - name: reaction in: query required: false description: Message reaction filter. schema: type: string enum: - NEGATIVE - POSITIVE - name: gptModel in: query required: false description: GPT model bucket filter. schema: type: string enum: - gpt-4.1 - gpt-4.1-mini - name: query in: query required: false description: Search query. schema: type: string - name: includeEmpty in: query required: false description: Include empty conversations. schema: type: boolean - name: scanLimit in: query required: false description: Maximum conversations to scan for filters. schema: type: integer minimum: 1 responses: '200': description: Successful SiteGPT API v2 response. content: application/json: schema: type: object required: - ok - data - meta properties: ok: type: boolean const: true data: type: object additionalProperties: true properties: conversations: type: array items: $ref: '#/components/schemas/Conversation' filters: $ref: '#/components/schemas/GenericObject' description: Echo of the applied filters. pagination: $ref: '#/components/schemas/Pagination' meta: $ref: '#/components/schemas/AgentResponseMeta' additionalProperties: false example: ok: true data: conversations: - id: conversation-id name: Example conversation createdAt: '2026-05-13T00:00:00.000Z' pagination: limit: 20 hasNextPage: false nextCursor: null meta: requestId: request-id '400': $ref: '#/components/responses/AgentError' '401': $ref: '#/components/responses/AgentError' '403': $ref: '#/components/responses/AgentError' '404': $ref: '#/components/responses/AgentError' '405': $ref: '#/components/responses/AgentError' security: - bearerAuth: - conversations:read components: schemas: Conversation: type: object description: A conversation thread between a visitor and the chatbot. additionalProperties: true properties: threadId: type: string chatbotId: type: string mode: type: string enum: - AI - AGENT description: AI answers automatically; AGENT means human takeover. startedAt: type: string format: date-time updatedAt: type: string format: date-time endedAt: type: - string - 'null' format: date-time escalated: type: boolean important: type: boolean resolved: type: boolean title: type: - string - 'null' tagIds: type: array items: type: string sessionId: type: - string - 'null' ipAddress: type: - string - 'null' pageUrl: type: - string - 'null' webhookUrl: type: - string - 'null' webhookTokenConfigured: type: boolean chatUserId: type: - string - 'null' chatUser: anyOf: - $ref: '#/components/schemas/ChatUser' - type: 'null' lead: anyOf: - $ref: '#/components/schemas/Lead' - type: 'null' totalMessages: type: integer totalPositiveMessages: type: integer totalNegativeMessages: type: integer totalGpt4MessagesCount: type: integer totalMessagesRead: type: integer totalMessagesReadByUser: type: integer unreadMessages: type: integer lastMessage: anyOf: - $ref: '#/components/schemas/Message' - type: 'null' messages: type: array items: $ref: '#/components/schemas/Message' description: >- Full message list; present on single-conversation reads and bulk action results, absent from list endpoints. GenericObject: type: object additionalProperties: true Pagination: type: object description: Cursor pagination state for paginated list endpoints. additionalProperties: false required: - limit - hasNextPage - nextCursor properties: limit: type: integer description: Page size used. hasNextPage: type: boolean nextCursor: type: - string - 'null' description: >- Pass as the cursor query parameter to fetch the next page. Null on the last page. AgentResponseMeta: type: object required: - requestId properties: requestId: type: string warnings: type: array items: type: string nextCursor: type: - string - 'null' additionalProperties: true ChatUser: type: object description: A website visitor identified through the chat widget. additionalProperties: true properties: id: type: string name: type: string email: type: string phone: type: string verified: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time Lead: type: object description: >- A captured lead. The top-level email convenience field is present on lead endpoints; conversation payloads embed the same record without it. additionalProperties: true properties: id: type: string chatbotId: type: string chatUser: $ref: '#/components/schemas/ChatUser' name: type: string phone: type: string email: type: string description: Convenience copy of chatUser.email. tags: type: array items: type: string customData: $ref: '#/components/schemas/GenericObject' description: Custom lead-form fields collected by the widget. important: type: boolean archived: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time Message: type: object description: >- One stored conversation turn. NORMAL_MESSAGE carries the visitor question plus the AI answer; USER_MESSAGE and AGENT_MESSAGE carry one side of a human conversation; SYSTEM_MESSAGE records events such as escalation. additionalProperties: true properties: messageId: type: string messageType: type: string description: NORMAL_MESSAGE, USER_MESSAGE, AGENT_MESSAGE, or SYSTEM_MESSAGE. systemMessageType: type: - string - 'null' description: Set on SYSTEM_MESSAGE rows; null otherwise. question: anyOf: - type: object additionalProperties: true properties: text: type: string timestamp: type: string - type: 'null' answer: anyOf: - type: object additionalProperties: true properties: text: type: string timestamp: type: string - type: 'null' reaction: type: string enum: - POSITIVE - NEGATIVE - NEUTRAL gptModel: type: - string - 'null' description: Public model label for AI answers; null on human turns. sources: type: array items: type: string description: Source URLs cited by the AI answer. agentId: type: - string - 'null' agentName: type: - string - 'null' iconUrl: type: - string - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time AgentError: type: object required: - ok - error - meta properties: ok: type: boolean const: false error: type: object required: - code - message properties: code: type: string message: type: string details: {} additionalProperties: false meta: type: object required: - requestId properties: requestId: type: string additionalProperties: true additionalProperties: false responses: AgentError: description: SiteGPT agent API error response. content: application/json: schema: $ref: '#/components/schemas/AgentError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: SiteGPT API token ````