curl --request GET \
--url https://api.onlyx.ai/v1/conversations/{conversationId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.onlyx.ai/v1/conversations/{conversationId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.onlyx.ai/v1/conversations/{conversationId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Get a conversation
Returns one conversation with the full fan (subscription, spend, notes, lists and salesOptOut), the open hand-off if there is one, and aiCanReply: whether the AI would answer this chat right now. Read it before writing to a fan so you know who you are talking to and whether a paid message is allowed. A conversation the credential cannot see is 404 CONVERSATION_NOT_FOUND.
Scope: requires inbox:read.
Rate limit: the general limit of 120 requests per 60 seconds per credential.
curl --request GET \
--url https://api.onlyx.ai/v1/conversations/{conversationId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.onlyx.ai/v1/conversations/{conversationId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.onlyx.ai/v1/conversations/{conversationId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Authorizations
An API key (onx_sk_…) created in OnlyX under Settings → API & MCP, or an OAuth access token (onx_at_…) issued to a connected app. Send it as Authorization: Bearer <credential>. API keys may also be sent as X-API-Key: <key>.
Path Parameters
The conversation id (cnv_…), from GET /v1/conversations.
40Response
The conversation, with the full fan, the open hand-off and whether the AI would reply.
Whether the AI would answer this chat right now: the creator's AI is on and set up, the chat is ai, and she is connected.
The creator whose inbox this conversation is in.
The fan, in full.
Show child attributes
Show child attributes
{ "avatarUrl": null, "conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b", "createdAt": "2026-03-02T18:21:07.000Z", "creatorId": "cre_8f2c1a9b0d7e4c3f2a1b", "customName": "Mike (birthday 14 May)", "displayName": "Mike", "id": "fan_6b2e8d4a1c9f3e7b5d0a", "lastActiveAt": "2026-09-25T21:40:12.000Z", "lastPurchaseAt": "2026-09-24T22:03:55.000Z", "lists": [ { "id": "lst_9c1d2e3f4a5b6c7d8e9f", "name": "VIP" } ], "muted": false, "notes": "Likes lingerie sets. Tips on Fridays.", "paidMessagesCents": 36500, "renewOn": true, "salesOptOut": false, "subscribed": true, "subscribedAt": "2026-03-02T18:21:07.000Z", "subscriptionExpiresAt": "2026-10-02T18:21:07.000Z", "subscriptionPriceCents": 999, "tipsCents": 12000, "totalSpentCents": 48500, "username": null }
The open hand-off on this conversation, or null.
Show child attributes
Show child attributes
{ "conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b", "createdAt": "2026-09-25T21:41:03.000Z", "creatorId": "cre_8f2c1a9b0d7e4c3f2a1b", "fanName": "Mike", "id": "esc_5e1f2a3b4c5d6e7f8a9b", "label": "Asks for a refund", "note": "He says the video he bought does not play and wants his money back.", "reason": "payment_dispute", "status": "open" }
The conversation id (cnv_…).
The latest message, or null for an empty conversation.
Show child attributes
Show child attributes
When the latest message was sent.
Who answers this chat (see Conversation.status).
ai, team, handoff, ai_off While status is team: when the chat returns to the AI on its own. Otherwise null.
Everything this fan has spent on the creator, in cents.
Fan messages not yet marked read in OnlyX.