> ## Documentation Index > Fetch the complete documentation index at: https://docs.convocore.app/llms.txt > Use this file to discover all available pages before exploring further. # Export Agent Conversations > Export chat sessions via the V3 Chat Export API — paginated by default (newest first), with sort and date-range filters. Reads from the PG mirror. Requires a paid workspace (hasEverPaid). Requires a **paid workspace** (`hasEverPaid`). Reads conversation content from the Postgres/Supabase mirror only (not Firestore). Each billable human-message session counts toward the monthly quota (50,000 included; overage billed in packs of 1,000). ## Modes | Mode | How | Behavior | | ----------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Paginated** (default) | Omit `convoIds` | Returns a page of chats from the Postgres mirror. Newest first by default. Use `cursor` / `hasMore` to page through. | | **Selected** | Pass `convoIds=id1,id2,...` | Exports only those conversation IDs (max 200 per request). | ## Query parameters | Param | Default | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------- | | `limit` | `20` | Page size in paginated mode (max **50**). | | `sort` | `desc` | `desc` = most recent chats first; `asc` = oldest first. | | `fromTs` | — | Inclusive start of range (unix **seconds**; ms also accepted). | | `toTs` | — | Inclusive end of range (unix **seconds**; ms also accepted). | | `cursor` | — | Opaque cursor from the previous response’s `nextCursor`. Keep the same `sort` / `fromTs` / `toTs` when paging. | | `convoIds` | — | Comma-separated IDs for selected mode (skips pagination). | | `format` | `json` | Response format. | ## Rate limits Per workspace (authenticated owner). In-memory counters (single process). Response includes `rateLimit.remainingHour` so clients can back off before a 429. | Limit | Unpaid | Paid (`hasEverPaid`) | | ------------------------------- | ---------------------- | ----------------------- | | Paginated page size | default 20, max **50** | default 20, max **100** | | Selected `convoIds` per request | **200** | **500** | | Export requests per hour | **300** | **1,500** | Export itself requires `hasEverPaid`, so live callers use the paid column. **429** when exceeded. ## Examples ### Newest chats (default) ```bash theme={null} curl -G "https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos/export" \ -H "Authorization: Bearer {SECRET_API_KEY}" \ --data-urlencode "limit=20" ``` ### Oldest first ```bash theme={null} curl -G "https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos/export" \ -H "Authorization: Bearer {SECRET_API_KEY}" \ --data-urlencode "sort=asc" \ --data-urlencode "limit=20" ``` ### Date range (unix seconds) ```bash theme={null} # e.g. 2026-01-01 .. 2026-01-31 UTC curl -G "https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos/export" \ -H "Authorization: Bearer {SECRET_API_KEY}" \ --data-urlencode "fromTs=1735689600" \ --data-urlencode "toTs=1738367999" \ --data-urlencode "sort=desc" \ --data-urlencode "limit=50" ``` ### Next page ```bash theme={null} curl -G "https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos/export" \ -H "Authorization: Bearer {SECRET_API_KEY}" \ --data-urlencode "limit=20" \ --data-urlencode "sort=desc" \ --data-urlencode "cursor={nextCursor_from_previous_response}" ``` ### Specific conversation IDs ```bash theme={null} curl -G "https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/convos/export" \ -H "Authorization: Bearer {SECRET_API_KEY}" \ --data-urlencode "convoIds=convo_a,convo_b,convo_c" ``` ## Example response (paginated) ```json theme={null} { "success": true, "message": "Exported 12 conversation(s) (15 billable session(s)). Paginated newest-first (supabase). ...", "mode": "paginated", "source": "supabase", "limit": 20, "hasMore": true, "nextCursor": "eyJ2IjoxLCJzb3J0IjoiZGVzYyIsInVuaXF1ZUlkIjoiLi4uIn0", "scannedConvoCount": 20, "query": { "sort": "desc", "fromTs": null, "toTs": null }, "usage": { "periodKey": "billing_...", "billableUsedThisRequest": 15, "billableUsedThisPeriod": 120, "includedQuota": 50000, "billableRemainingThisPeriod": 49880, "summary": "Used 120 / 50,000 billable session exports this billing cycle..." }, "data": [] } ``` ## Notes * Reads from the **Supabase `convos` mirror** (`convoTurns` + `convoSessions`), not live Firestore. * Default sort is **most recent first** (`sort=desc`). * `fromTs` / `toTs` filter on the conversation’s `ts` field (inclusive). * When paging, reuse the same `sort`, `fromTs`, and `toTs` with `cursor`. * Conversations with no human messages are skipped (not billable). * Past sessions under a convo that contain human turns are each billable. * Response includes `usage` for quota tracking. ## Related documentation * [Export Single Conversation](/api-reference/v3/conversations/export_single) * [Conversations tab (dashboard export)](/features/conversations-tab) ## OpenAPI ````yaml GET /agents/{agentId}/convos/export openapi: 3.0.3 info: title: Convocore OpenAPI description: Full API reference for Convocore version: 1.0.4 servers: - url: https://eu-gcp-api.vg-stuff.com/v3 security: [] paths: /agents/{agentId}/convos/export: get: tags: - Conversations summary: Export Agent Conversations description: >- Export chat sessions for an agent from the PG mirror. Paginated mode (omit convoIds): newest-first by default, sort=asc for oldest-first, optional fromTs/toTs unix range, cursor pagination. Or pass convoIds for specific chats. Requires a paid workspace (hasEverPaid). Paid: up to 100/page, 500 selected IDs, 1500 req/hour. operationId: conversationRouter-exportAgentConvos parameters: - name: agentId in: path required: true schema: type: string - name: format in: query required: false schema: anyOf: - not: {} - type: string enum: - csv - json default: json - name: convoIds in: query required: false schema: type: string - name: cursor in: query required: false schema: type: string - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: sort in: query required: false schema: anyOf: - not: {} - type: string enum: - desc - asc default: desc - name: fromTs in: query required: false schema: type: number - name: toTs in: query required: false schema: type: number responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string data: type: array items: $ref: '#/components/schemas/object_eb434434' usage: $ref: '#/components/schemas/object_e7daf66c' rateLimit: $ref: '#/components/schemas/requestsPerHour_remainingHour_0134a2' hasMore: type: boolean nextCursor: type: string nullable: true limit: type: number mode: type: string enum: - paginated - selected scannedConvoCount: type: number source: type: string enum: - supabase query: type: object properties: sort: type: string enum: - desc - asc fromTs: type: number nullable: true toTs: type: number nullable: true required: - sort - fromTs - toTs additionalProperties: false required: - success - message - data additionalProperties: false default: $ref: '#/components/responses/error' security: - Authorization: [] components: schemas: object_eb434434: type: object properties: userEmail: type: string userName: type: string userPhone: type: string userAddress: type: string userCompany: type: string userWebsite: type: string notes: type: string userProfilePic: type: string stage: $ref: '#/components/schemas/string_015e8ef8' value: anyOf: - type: number - type: string currency: type: string expectedCloseDate: type: string subIndustry: type: string source: type: string language: type: string linkedIn: type: string facebook: type: string instagram: type: string demoDate: type: string demoTime: type: string demoLink: type: string lostReason: type: string lastActivityDate: anyOf: - type: string - type: number ID: type: string userID: type: string description: >- UserID/ConvoID it is the phone number of the user if it is a call and is NOT unique for every individual call/conversation. campaignId: type: string description: The campaign id that the call may belong to. userImage: type: string description: >- This is the image of the user that is used to display in the lead card. socialHandle: type: string isFollowingBusiness: type: boolean socialVerified: type: boolean userOs: type: string userBrowser: type: string ipAddress: type: string browserTimezone: type: string description: >- IANA timezone auto-detected from the visitor's browser (Intl.DateTimeFormat), used to skip asking for timezone on calendar/scheduling flows. countryCode: type: string origin: {} whatsappPhoneNumberId: type: string whatsappBusinessNumber: type: string whatsappDisplayPhoneNumber: type: string whatsappBusinessAccountId: type: string voiceflowV4Session: $ref: >- #/components/schemas/sessionKey_projectId_environmentAlias_updatedAt_8d33a7 messagesNum: type: number interactionsNum: type: number ts: type: number tags: type: array items: type: string convoTimeSeconds: type: number firstMessageTS: type: number lastMessageTS: type: number userPlatform: type: string state: $ref: '#/components/schemas/string_ce724de6' smbContact: type: boolean smbContactName: type: string smbContactRemovedAt: type: number smbLastSeenAt: type: number humanClaimedAt: type: number nullable: true humanLastRepliedAt: type: number nullable: true pendingAiReplyAt: type: number nullable: true chatAssignedTo: type: string chatAssignedToIds: type: array items: type: string assignedToUsers: type: array items: $ref: '#/components/schemas/object_ea6297dc' handoffHistory: $ref: '#/components/schemas/array_514028d6' isTyping: type: boolean description: Indicates if the human agent is currently typing a response lastModified: type: number sessionsNum: type: number lang: type: string vapi: $ref: '#/components/schemas/object_c0b635a3' ratingFrom5: type: number totalUserInteractions: type: number isBlocked: type: boolean nodesInfo: $ref: '#/components/schemas/currentNode_f37652' capturedVariables: {} campaignCalls: type: array items: {} sessions: type: array items: {} endReason: type: string isTest: type: boolean metrics: type: array items: {} notifyToUserId: type: string averageLatency: type: number voice: $ref: '#/components/schemas/latestSessionId_listenUrl_listenUrlUNIX_d762bb' detailedCost: $ref: >- #/components/schemas/totalCreditsConsumed_speechGenCost_transcriberCost_twilioCost_8e1967 summary: type: string description: This is the summary of the conversation that is generated by the AI. shortSummary: type: string description: >- Web-chat only: 3-4 word sidebar title generated with the long AI summary. requestedTeamKey: type: string delegatedBy: type: string description: ID of the user who delegated this chat delegatedAt: type: number description: Unix timestamp when the chat was delegated lastViewed: type: number description: Unix timestamp when the conversation was last viewed/opened isArchived: type: boolean description: Whether the conversation has been moved to the archive archivedAt: type: number description: Unix timestamp when the conversation was archived archivedBy: type: string description: Email or uid of the user who archived the conversation isResolved: type: boolean description: >- Whether a human marked this conversation resolved (and passed back to AI) resolvedAt: type: number description: Unix ms when the conversation was resolved resolvedBy: type: string description: Client ID of the human who clicked Resolve resolvedByEmail: type: string description: Email of the human who resolved (for display/tags) lastResolvedAssigneeId: type: string description: Stable assignee to notify if the chat is reopened reopenedAt: type: number description: Unix ms when a resolved chat was reopened reopenReason: type: string description: Short reason from AI when auto-reopening after customer reply csat: $ref: >- #/components/schemas/satisfaction10_ease10_comment_submittedAt_6270d3 note: type: string assignedTo: $ref: '#/components/schemas/object_ea6297dc' hotScore: type: number hotLabel: type: string enum: - hot - warm - cold crmActivities: type: array items: $ref: '#/components/schemas/object_dc83268b' crmAlerts: $ref: >- #/components/schemas/overdueECD_overdueActivity_staleLead_responded_9dc18b contactIdentityId: type: string linkedChannels: type: array items: type: string crossChannelContext: type: string leadScore: type: number default: 0 description: Current lead score (0-100) funnelStepsMatched: $ref: '#/components/schemas/array_b2ca0742' funnelScoreHistory: $ref: '#/components/schemas/array_ab56e734' funnelNotificationSent: $ref: '#/components/schemas/boolean_b29b0a71' funnelLastEvaluated: type: number description: Unix timestamp of last funnel evaluation funnelExtractedData: $ref: '#/components/schemas/object_302324ac' funnelSummary: type: string description: AI-generated conversation summary for email notifications tokenUsage: $ref: '#/components/schemas/object_c0a62c0b' inboundEngagementState: $ref: '#/components/schemas/object_54e6261a' additionalProperties: false object_e7daf66c: type: object properties: periodKey: type: string billableUsedThisRequest: type: number billableUsedThisPeriod: type: number includedQuota: type: number billableRemainingThisPeriod: type: number overageUsedThisPeriod: type: number overagePacksCharged: type: number exportRequestCount: type: number logId: type: string summary: type: string required: - periodKey - billableUsedThisRequest - billableUsedThisPeriod - includedQuota - billableRemainingThisPeriod - overageUsedThisPeriod - overagePacksCharged - exportRequestCount - summary additionalProperties: false requestsPerHour_remainingHour_0134a2: type: object properties: requestsPerHour: type: number remainingHour: type: number required: - requestsPerHour - remainingHour additionalProperties: false string_015e8ef8: type: string enum: - new - engaged - email_sent - follow_up - info_req - demo_req - demo_conf - demo_done - proposal - negotiation - trial - won - lost sessionKey_projectId_environmentAlias_updatedAt_8d33a7: type: object properties: sessionKey: type: string projectId: type: string environmentAlias: type: string updatedAt: type: number resolvedRuntime: type: string enum: - legacy - v4 required: - sessionKey - projectId additionalProperties: false description: >- Voiceflow v4 session key persisted on the chat/convo doc for cross-request continuity string_ce724de6: type: string enum: - requested_chat - human-chatting - ai-chatting - ended_chat object_ea6297dc: type: object properties: userId: type: string name: type: string email: type: string photoUrl: type: string note: type: string assignedAt: anyOf: - type: string - type: number status: type: string enum: - pending - accepted - done required: - userId additionalProperties: false array_514028d6: type: array items: $ref: '#/components/schemas/object_d4f753e9' description: Complete history of all handoffs for this conversation object_c0b635a3: type: object properties: cost: type: number callDuration: type: number recordingUrl: type: string syncRecordingUrl: type: string callerPhoneNumber: type: string calleePhoneNumber: type: string callStatus: type: string callError: type: string additionalProperties: false currentNode_f37652: type: object properties: currentNode: type: string additionalProperties: false latestSessionId_listenUrl_listenUrlUNIX_d762bb: type: object properties: latestSessionId: type: string listenUrl: type: string description: This is the url that is used to listen to the call in realtime. listenUrlUNIX: type: number additionalProperties: false totalCreditsConsumed_speechGenCost_transcriberCost_twilioCost_8e1967: type: object properties: totalCreditsConsumed: type: number speechGenCost: type: number transcriberCost: type: number twilioCost: type: number llmCost: type: number additionalProperties: false satisfaction10_ease10_comment_submittedAt_6270d3: type: object properties: satisfaction10: type: number minimum: 1 maximum: 10 ease10: type: number minimum: 1 maximum: 10 comment: type: string submittedAt: type: number channel: type: string surveyVersion: type: number additionalProperties: false description: Post-resolve CSAT scores (1-10), separate from ratingFrom5 object_dc83268b: type: object properties: id: type: string title: type: string type: $ref: '#/components/schemas/string_3f503ce4' date: anyOf: - type: string - type: number dueDate: anyOf: - type: string - type: number completed: type: boolean responded: type: boolean firstChannel: $ref: '#/components/schemas/string_24adc72c' firstEngaged: type: boolean secondChannel: $ref: '#/components/schemas/string_24adc72c' secondEngaged: type: boolean note: type: string notesHistory: $ref: '#/components/schemas/array_a78409b8' metadata: type: object additionalProperties: {} required: - type additionalProperties: false overdueECD_overdueActivity_staleLead_responded_9dc18b: type: object properties: overdueECD: type: boolean overdueActivity: type: boolean staleLead: type: boolean responded: type: boolean newHandoffAssigned: type: boolean additionalProperties: false array_b2ca0742: type: array items: type: string default: [] description: Array of matched funnel step IDs array_ab56e734: type: array items: $ref: '#/components/schemas/object_b7a75c76' default: [] description: History of score changes boolean_b29b0a71: type: boolean default: false description: Whether notification email has been sent object_302324ac: type: object additionalProperties: {} description: Extracted business data from conversations object_c0a62c0b: type: object properties: cumulativeInputTokens: type: number cumulativeOutputTokens: type: number cumulativeTotalTokens: type: number cumulativeUsd: type: number lastTurnInputTokens: type: number lastTurnOutputTokens: type: number lastTurnTotalTokens: type: number lastTurnUsd: type: number lastTurnModelId: type: string lastTurnContextWindow: type: number lastTurnInputUsdPer1k: type: number lastTurnOutputUsdPer1k: type: number lastTurnTs: type: number usagePerModel: $ref: '#/components/schemas/object_9fd4236e' additionalProperties: false description: Cumulative + last-turn LLM token usage for this conversation object_54e6261a: type: object properties: firstDecisionAt: type: number firstDecisionShouldReply: type: boolean lastDecisionAt: type: number lastDecisionShouldReply: type: boolean lastDecisionReason: type: string aiOwnedThread: type: boolean ignoreThread: type: boolean lastTriggeredBy: type: string enum: - phrase - ai_rule - ownership additionalProperties: false description: >- Per-thread state for inbound engagement decisions, ownership, and persistent ignore/reply behavior. message_11569e: type: object properties: message: type: string required: - message additionalProperties: false object_d4f753e9: type: object properties: requestedAt: type: number acceptedAt: type: number completedAt: type: number acceptedBy: type: string description: Agent ID who accepted organizationId: type: string description: >- Organization ID that accepted the handoff. Set to "convocore" for main dashboard, or the org ID for specific organizations requestedTeamKey: type: string teamIds: $ref: '#/components/schemas/array_1a29d528' teamKeys: $ref: '#/components/schemas/array_fa08fae4' additionalProperties: false string_3f503ce4: type: string enum: - Message - Call - Email - Demo - Meeting - Follow-Up - Note - Stage Change - Handoff - System string_24adc72c: type: string enum: - LinkedIn - WhatsApp - Instagram - Facebook - Email - Phone/Call - Zoom/Video - In Person - Referral - Web Chat - Unknown array_a78409b8: type: array items: $ref: '#/components/schemas/agentId_agentName_text_timestamp_53e777' object_b7a75c76: type: object properties: timestamp: type: number stepId: type: string stepName: type: string pointsAdded: type: number newScore: type: number extractedData: type: object additionalProperties: {} messageContext: type: string required: - timestamp - stepId - stepName - pointsAdded - newScore additionalProperties: false object_9fd4236e: type: object additionalProperties: $ref: >- #/components/schemas/modelId_inputTokens_outputTokens_totalTokens_99d4fb array_1a29d528: type: array items: type: string description: Team IDs the agent who accepted belongs to array_fa08fae4: type: array items: type: string description: Team keys the agent who accepted belongs to agentId_agentName_text_timestamp_53e777: type: object properties: agentId: type: string agentName: type: string text: type: string timestamp: anyOf: - type: string - type: number required: - text additionalProperties: false modelId_inputTokens_outputTokens_totalTokens_99d4fb: type: object properties: modelId: type: string inputTokens: type: number outputTokens: type: number totalTokens: type: number usd: type: number lastUsedTs: type: number additionalProperties: false responses: error: description: Error response content: application/json: schema: type: object properties: message: type: string code: type: string issues: type: array items: $ref: '#/components/schemas/message_11569e' required: - message - code additionalProperties: false securitySchemes: Authorization: type: http scheme: bearer ````