> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Get conversation > Retrieve a conversation with its full message history — alternating user and assistant turns. Each assistant turn carries the originating `jobId` and an `omniChatUrl` deep link. The conversations returned by this API depend on the type of API key being used: - Organization API keys can access any conversation in the organization - Personal Access Tokens can only access the authenticating user's conversations ## OpenAPI ````yaml /api/openapi.yaml get /v1/ai/conversations/{conversationId} openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/ai/conversations/{conversationId}: get: tags: - AI summary: Get conversation description: > Retrieve a conversation with its full message history — alternating user and assistant turns. Each assistant turn carries the originating `jobId` and an `omniChatUrl` deep link. The conversations returned by this API depend on the type of API key being used: - Organization API keys can access any conversation in the organization - Personal Access Tokens can only access the authenticating user's conversations operationId: getConversation parameters: - name: conversationId in: path required: true schema: type: string format: uuid description: The unique identifier of the conversation responses: '200': description: Conversation retrieved successfully content: application/json: schema: type: object required: - id - userId - organizationId - createdAt - updatedAt - messages properties: id: type: string format: uuid description: The unique identifier for this conversation. example: 660e8400-e29b-41d4-a716-446655440001 userId: type: string format: uuid description: The user ID who created this conversation. example: 990e8400-e29b-41d4-a716-446655440004 organizationId: type: string format: uuid description: The organization that owns this conversation. example: 880e8400-e29b-41d4-a716-446655440003 createdAt: type: string format: date-time description: When the conversation was created. example: '2025-01-15T10:00:00.000Z' updatedAt: type: string format: date-time description: When the conversation was last modified. example: '2025-01-15T10:01:30.000Z' messages: type: array description: >- Ordered list of messages in the conversation, alternating between user and assistant turns. items: type: object required: - role - content - timestamp properties: role: type: string enum: - user - assistant description: The role of the message sender. example: user content: type: string description: >- The message content. For user messages, this is the prompt. For assistant messages, this is the AI's response in Markdown format. example: What are the top 5 products by revenue? timestamp: type: string format: date-time description: When this message was created. example: '2025-01-15T10:00:00.000Z' jobId: type: string format: uuid description: > **Only present for assistant messages.** The ID of the AI job that generated this response. Use this with the [Get AI job status](/api/ai/get-ai-job-status) endpoint to retrieve job details. example: 550e8400-e29b-41d4-a716-446655440000 omniChatUrl: type: string format: uri description: > **Only present for assistant messages.** URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible. example: >- https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001 examples: conversation: summary: A conversation with multiple turns value: id: 660e8400-e29b-41d4-a716-446655440001 userId: 990e8400-e29b-41d4-a716-446655440004 organizationId: 880e8400-e29b-41d4-a716-446655440003 createdAt: '2025-01-15T10:00:00.000Z' updatedAt: '2025-01-15T10:05:00.000Z' messages: - role: user content: What are the top 5 products by revenue? timestamp: '2025-01-15T10:00:00.000Z' - role: assistant content: |- ### Top 5 Products by Revenue 1. **Sunglasses** - $678,994 2. **Jeans** - $475,072 3. **T-Shirt** - $320,150 4. **Sneakers** - $289,033 5. **Hat** - $201,487 timestamp: '2025-01-15T10:01:30.000Z' jobId: 550e8400-e29b-41d4-a716-446655440000 omniChatUrl: >- https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001 - role: user content: Show me revenue by month for sunglasses timestamp: '2025-01-15T10:03:00.000Z' - role: assistant content: |- ### Sunglasses Revenue by Month - January: $52,430 - February: $48,221 - March: $61,992 timestamp: '2025-01-15T10:05:00.000Z' jobId: 550e8400-e29b-41d4-a716-446655440010 omniChatUrl: >- https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001 '400': description: | Bad Request Possible error messages: - `Invalid conversation ID format. Must be a valid UUID.` content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: | Unauthorized Possible error messages: - `Missing or invalid API key` content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | Forbidden Possible error messages: - `User does not have USE_AI permission` - `User-scoped token cannot access another user's conversation` content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: '404' detail: Conversation not found '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````