Data management

Status and recent activity

GET /api/connections?userRef= answers the three questions you have about a user: are they connected, how active have they been, and is their history whole.

{
  "userRef": "user_123",
  "connected": true,
  "needsReauth": false,
  "recentConversationCount": 12,
  "recentWindowDays": 30,
  "historyComplete": true,
  "oldestConversationAt": "2024-10-30T15:34:30.894Z",
  "connections": [ { "id": "…", "accountId": "3f9c…", "status": "active", "conversationCount": 142, "recentConversationCount": 12, "historyComplete": true, "oldestConversationAt": "2024-10-30T15:34:30.894Z", "newestConversationAt": "2026-09-26T18:02:11.000Z", "…": "…" } ]
}

connected is true when at least one connection is active.
needsReauth is true when at least one connection is needs_reauth. This is the only status that should trigger a “please reconnect” message. A revoked connection was either replaced after a reconnect or deleted by the user on purpose.
recentConversationCount counts conversations whose first message is dated within the last 30 days, evaluated at request time. It measures what the user did, not what Verso imported: an old history imported yesterday counts for nothing, and continuing an old conversation does not move it into the window.
historyComplete is true once the whole history of the connection has been imported, and oldestConversationAt / newestConversationAt give its span (first message of the oldest and of the newest conversation). While the initial import is still running, historyComplete is false and the span only reflects what has arrived so far; the moment it turns true is announced by the history.completed webhook.

Always query by userRef. Connection ids change when a user reconnects, and one user may hold several connections. Each connection carries an accountId, stable for one ChatGPT account within your app: two connections with the same accountId are the same account, for example an old revoked one and its replacement. A ChatGPT account can be connected by only one user of your app. Each connection also carries what the provider says about the account: plan (free, go, plus, pro, team, enterprise…) and country (ISO 3166-1 alpha-2). Both are null until the first sync. Ads are shown to free and go accounts only. An expired session is detected at the next sync, so connected can stay true for a few hours after the provider invalidated the session. lastSyncAt tells you when it was last verified.

Your whole user base

For a periodic run over every user, GET /api/users returns pages of users in the same shape, oldest first.

curl -s "https://connect.tryverso.ai/api/users?limit=500&offset=0" \
  -H "Authorization: Bearer $VERSO_API_KEY"

{
  "users": [
    { "userRef": "user_123", "connected": true, "needsReauth": false, "recentConversationCount": 12, "connections": [ "…" ] },
    { "userRef": "user_124", "connected": false, "needsReauth": false, "recentConversationCount": 0, "connections": [] }
  ],
  "total": 10432,
  "limit": 500,
  "offset": 0,
  "recentWindowDays": 30
}

limit goes up to 500, so ten thousand users take twenty calls, well within the rate limit of one minute. Users who opened a connect link but never finished logging in are listed with connected: false and no connections.

Reading conversations

GET /api/conversations?connectionId= returns pages of conversations, newest update_time first.

async function fetchAll(connectionId: string) {
  const all = [];
  for (let offset = 0; ; offset += 100) {
    const res = await fetch(
      `https://connect.tryverso.ai/api/conversations?connectionId=${connectionId}&limit=100&offset=${offset}`,
      { headers: { Authorization: `Bearer ${process.env.VERSO_API_KEY}` } },
    );
    const page = await res.json();
    all.push(...page.conversations);
    if (all.length >= page.total) return all;
  }
}

Because the list is ordered by update_time, a conversation the user continues moves back to the top. To detect changes cheaply, compare update_time with what you stored.

Shape of a conversation

{
  "id": "6a1f…",
  "external_id": "68d9c2a1-3f0e-8005-b2c1-7e2f0d1a9b3c",
  "title": "Help me build a REST API",
  "update_time": "2026-09-20T10:05:00Z",
  "payload": {
    "title": "Help me build a REST API",
    "messages": [
      {
        "role": "user",
        "content": "I need a REST API for managing tasks…",
        "timestamp": "2026-09-20T10:00:00.000Z",
        "id": "aaa-…",
        "contentType": "text"
      },
      {
        "role": "assistant",
        "content": "I'll help you build a task management API…",
        "timestamp": "2026-09-20T10:00:05.000Z",
        "id": "bbb-…",
        "contentType": "text",
        "model": "gpt-4o",
        "status": "finished_successfully",
        "endTurn": true
      }
    ]
  }
}

messages is the conversation’s current branch in chronological order. System messages and empty nodes are dropped; messages the user regenerated or branched away from are not included.

Field	Always present	Description
`role`	Yes	`user`, `assistant` or `tool`
`content`	Yes	Text. Empty when the message only carries attachments.
`timestamp`	Yes	ISO 8601, or `null` when the provider gave none
`id`	Usually	The provider’s message id
`contentType`	Usually	`text`, `multimodal_text`, `code`…
`model`	Assistant messages	Model that produced the message, e.g. `gpt-4o`
`status`, `endTurn`	Usually	Provider status flags
`attachments`	When present	Files and images: `type`, `asset_pointer`, `name`, `size_bytes`, `width`, `height`
`contentReferences`	When present	Citations embedded in an assistant answer

Attachments are metadata only for now. The files are stored by Verso but cannot be retrieved through the API yet.

Ads shown in a conversation

ChatGPT shows sponsored results to Free and Go accounts under some answers. Each conversation carries them in ads, keyed to the user message they answered:

{
  "ads": [
    {
      "messageId": "aaa-…",
      "adId": "06af3c16-b8df-7e62-8000-d557ca1764a8:2",
      "placement": "conversational_bottom",
      "visibility": "allowed",
      "type": "single_advertiser_ad_unit",
      "advertiser": { "id": "adacct_6aa3…", "name": "Acme Audio", "url": "https://www.acme-audio.example/?utm_source=chatgpt.com" },
      "preamble": "To compare noise-cancelling headphones under $300, here is an option.",
      "cards": [
        { "title": "Noise-cancelling headphones", "body": "Over-ear and in-ear models, free returns.", "url": "https://www.acme-audio.example/headphones?utm_source=chatgpt.com", "imageUrl": "https://images.openai.com/…" }
      ],
      "firstSeenAt": "2026-11-11T09:02:17.000Z"
    }
  ]
}

messageId is the id of the user message in payload.messages; visibility is allowed for an ad that was displayed. ads is read within two days of the conversation’s last update, the time the provider keeps it: it is empty for paid accounts (see plan on the connection), for conversations without any, and for conversations that were already older when the user connected. For those, and for every ad regardless of age, use the impressions below.

Every ad the account saw

The provider also keeps, for months, the history of every ad the account saw (viewed) or clicked (opened). Verso reads it back to its start over the first syncs, then picks up the new impressions at each sync, and matches each one to the conversation that was open at that moment. GET /api/ad-impressions?connectionId= lists them newest first:

{
  "impressions": [
    {
      "id": "uuid",
      "occurredAt": "2026-09-20T10:00:06.000Z",
      "action": "viewed",
      "adId": "06af3c16-b8df-7e62-8000-d557ca1764a8",
      "advertiser": { "id": "adacct_6aa3…", "name": "Acme Audio", "url": "https://www.acme-audio.example" },
      "title": "Noise-cancelling headphones",
      "body": "Over-ear and in-ear models, free returns.",
      "url": "https://www.acme-audio.example/headphones?utm_source=chatgpt.com",
      "imageUrl": "https://images.openai.com/…",
      "conversationId": "uuid",
      "messageId": "5882cd12-a1e6-4a82-9842-a3146f9e7262"
    }
  ],
  "total": 234,
  "limit": 100,
  "offset": 0
}

conversationId is exact when Verso read the ad in the conversation (messageId set, the same id as in ads), the conversation active at that moment otherwise, and null when none of the imported conversations covers it. Each conversation also carries its own impressions as adImpressions, oldest first, so a conversation from before the user connected still shows the ads it had. A click is its own row, next to the viewed row of the same adId; adId is the ad’s request id, which ads[].adId extends with :<n>.

Sync cadence

Every connection is synced by a background worker that lists the account’s conversations, fetches the ones that changed, and stores them. The pace adapts to the account and to the provider’s limits.

Situation	Next sync
Right after the connection	Within a minute
History still being backfilled	Every 15 minutes, until the whole history is imported
Last sync found something new	4 hours
Last sync found nothing	Twice the previous interval, up to 48 hours
The provider rate-limited the account	1 hour

The initial backfill fetches the most recent conversations first, then works backwards; a large history takes hours because the provider limits how fast one account can be read. Each sync that inserts or updates at least one conversation sends data.imported. When the backfill reaches the end of the history, history.completed is sent once, with the connection’s figures, and historyComplete turns true on GET /api/connections.

Re-authentication

When the provider rejects the stored session, the connection becomes needs_reauth and reauth.needed is sent. Sign a new connect link:

const { url } = await signLink(
  { appId: "app_yourapp", userRef, scopes: ["conversations:read"], purpose: "connect" },
  process.env.VERSO_APP_SECRET!,
);
// send url to the user

After the user logs in, the new connection replaces the old one and sync resumes where it stopped. The conversations already imported stay readable in the meantime.

Getting started

Guides

Resources

Status and recent activity

Your whole user base

Reading conversations

Shape of a conversation

Ads shown in a conversation

Every ad the account saw

Sync cadence

Re-authentication

​Status and recent activity

​Your whole user base

​Reading conversations

​Shape of a conversation

​Ads shown in a conversation

​Every ad the account saw

​Sync cadence

​Re-authentication

Status and recent activity

Your whole user base

Reading conversations

Shape of a conversation

Ads shown in a conversation

Every ad the account saw

Sync cadence

Re-authentication