> ## Documentation Index > Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt > Use this file to discover all available pages before exploring further. # List scope conversations > Returns a page of conversation summaries (most recently updated first) for a scope. Use `id=0` for your cross-scope recent history. Optional `userId`, `toolName`, and `timeframe` filters apply. Pass `nextPageToken` as `pageToken` to fetch the next page. **Requires:** `scopes:read` ## OpenAPI ````yaml https://api.getmodus.com/openapi.json get /api/v1/scopes/{id}/conversations openapi: 3.0.3 info: title: Modus Public API version: 1.0.0 servers: [] security: - bearerAuth: [] tags: - name: Scopes description: Create, configure, deploy, and manage scopes. - name: Scopes · Conversations description: Read scope conversation threads. - name: Scopes · Supervision description: Scope supervision sub-resource. - name: Scopes · Memories description: Long-term memory stored per scope. - name: Scopes · Chat description: Chat with a published scope. - name: Scopes · Context description: Compose a scope’s context without an LLM call. - name: Modus · Chat description: Chat with Modus — your org-wide assistant. - name: Modus · Conversations description: Read Modus and cross-scope conversation threads. - name: Modus · Context description: Compose full-environment context without an LLM call. - name: Workflows description: Create, configure, deploy, and manage workflows. - name: Workflows · Runs description: Inspect workflow run history. - name: Workflows · Interfaces description: Slack / MCP / Teams interface management. - name: Connections description: Read connected integrations. - name: Tools description: Catalog of tools/integrations a scope can select in its toolset. - name: Suggestions description: Approved suggested questions and first-party suggestion usage events. - name: Context description: Create and manage organization context items. - name: Usage description: Organization LLM usage reporting. - name: Users description: Organization and membership management. - name: Runs · Streaming description: 'Run lifecycle: stream, poll, resume, interrupt, and cancel executions.' - name: Scopes · Runs description: Run a published or draft scope. - name: Modus · Runs description: Run the Modus home agent. paths: /api/v1/scopes/{id}/conversations: get: tags: - Scopes · Conversations summary: List scope conversations description: >- Returns a page of conversation summaries (most recently updated first) for a scope. Use `id=0` for your cross-scope recent history. Optional `userId`, `toolName`, and `timeframe` filters apply. Pass `nextPageToken` as `pageToken` to fetch the next page. **Requires:** `scopes:read` operationId: ScopeConversationsController_list parameters: - name: id required: true in: path description: Numeric scope id. Use 0 for cross-scope recent history. schema: example: 42 type: number - name: pageToken required: false in: query description: >- Opaque page token from a previous response's `nextPageToken`. Omit for the first page. schema: example: eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MjV9 type: string - name: page required: false in: query description: >- Legacy zero-indexed page number. Defaults to 0. Prefer `pageToken`; if both are supplied, `pageToken` wins. schema: minimum: 0 example: 0 type: number - name: pageSize required: false in: query description: Items per page. Defaults to 10, clamped to 100. schema: minimum: 1 maximum: 100 example: 10 type: number - name: userId required: false in: query description: >- Filter by user id who participated in the conversation. Exact match against the `conversation_interactions.user_id` column. schema: example: user_abc type: string - name: toolName required: false in: query description: >- Filter by tool name invoked in the conversation. Applied post-fetch (requires reading message blobs); use `includeTools=true` to also see the matched tools. schema: example: sql_runner type: string - name: timeframe required: false in: query description: Filter by activity recency. Coarse server-side buckets. schema: example: last_7_days type: string enum: - last_day - this_week - this_month - last_7_days - last_30_days - name: includeTools required: false in: query description: >- When true, populate `toolsUsed` on each list item by scanning message blobs. Defaults to false to keep the list cheap. schema: example: false type: boolean responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListConversationsResponseDto' '400': description: >- Malformed request — invalid query parameters or request body (`code: BAD_REQUEST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: BAD_REQUEST status: INVALID_ARGUMENT message: Invalid value for query parameter `pageSize`. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '401': description: 'Missing, invalid, or expired access token (`code: UNAUTHORIZED`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: UNAUTHORIZED status: UNAUTHENTICATED message: Missing or invalid access token. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '403': description: >- Authenticated, but the token lacks a required scope (`code: FORBIDDEN`). The missing scopes are listed in `info`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: FORBIDDEN status: PERMISSION_DENIED message: Missing required scope(s) for this operation. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: missing: - '404': description: >- The resource does not exist, or you do not have access to it (`code: NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: NOT_FOUND status: NOT_FOUND message: Resource not found. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '500': description: 'An unexpected server error occurred (`code: INTERNAL_ERROR`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: INTERNAL_ERROR status: INTERNAL message: An unexpected error occurred. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS security: - bearerAuth: [] servers: - url: https://api.getmodus.com components: schemas: ListConversationsResponseDto: type: object properties: conversations: description: Page of conversation summaries, newest-updated first. type: array items: $ref: '#/components/schemas/ConversationListItemDto' nextPageToken: type: string nullable: true description: >- Opaque token for the next page. `null` when there are no further pages. example: eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MTB9 totalCount: type: number description: >- Total threads visible in the scanned window after filters. Not a global count. example: 47 page: type: number description: >- Legacy echo of the requested 0-indexed page. Retained for SPA backwards-compatibility; new callers should rely on `pageToken` / `nextPageToken`. example: 0 pageSize: type: number description: >- Legacy echo of the requested `pageSize`. Retained for SPA backwards-compatibility. example: 10 required: - conversations - nextPageToken - totalCount ErrorResponseDto: type: object properties: error: $ref: '#/components/schemas/ErrorEnvelopeDto' required: - error ConversationListItemDto: type: object properties: threadId: type: string description: Opaque thread id. example: agent_42_abc-xyz scopeId: type: number description: >- Numeric scope id returned by the list adapter. This is not conversation ownership. example: 42 firstMessage: type: string description: >- Preview of the first user turn, used as a list-row caption. Falls back to a stable placeholder when the thread has no human turn yet. example: Run the churn analysis for last 30 days. title: type: string nullable: true description: >- User-managed display title. Null until the user renames the conversation. example: Q3 Revenue Analysis messageCount: type: number description: Total number of message turns in the (post-collapse) conversation. example: 12 createdAt: type: string description: ISO-8601 timestamp of the first checkpoint. example: '2026-05-01T10:00:00.000Z' updatedAt: type: string description: ISO-8601 timestamp of the latest checkpoint. example: '2026-05-01T11:00:00.000Z' toolsUsed: description: >- Distinct tool names invoked across this conversation. Present only when `includeTools=true` is requested. example: - sql_runner type: array items: type: string userIds: description: Distinct user ids that participated in this thread. example: - user_abc type: array items: type: string required: - threadId - scopeId - firstMessage - title - messageCount - createdAt - updatedAt - userIds ErrorEnvelopeDto: type: object properties: code: description: Modus-specific machine code. allOf: - $ref: '#/components/schemas/ApiErrorCode' status: description: Canonical status string for the error. allOf: - $ref: '#/components/schemas/ApiErrorStatus' message: type: string example: Skill was not found or you lack permission. requestId: type: string example: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: type: object description: >- Optional domain-specific context. Shape varies per endpoint — see the operation's error response examples. additionalProperties: true example: skillId: sk_abc123 required: - code - status - message - requestId ApiErrorCode: type: string enum: - VALIDATION - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Modus-specific machine code. ApiErrorStatus: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - ALREADY_EXISTS - RESOURCE_EXHAUSTED - INTERNAL description: Canonical status string for the error. securitySchemes: bearerAuth: scheme: bearer bearerFormat: Modus PAT (modus___) or OAuth 2.1 access token type: http description: >- A Modus personal access token (`modus___`) or an OAuth 2.1 access token, sent as `Authorization: Bearer `. ````