> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryverso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List ad impressions

> Returns the ads ChatGPT showed (`viewed`) or the user clicked (`opened`)
on the connected account, newest first, paginated with `limit` and
`offset`. The rows come from the account's ads history, which the
provider keeps for months: they cover conversations from long before
the user connected. Verso reads the history back to its start over the
first syncs, then picks up the new impressions at each sync.

Each impression is matched to the conversation that was open at that
moment when Verso holds it (`conversationId`, and `messageId` when the
ad was also read in the conversation). The same rows are listed on each
conversation as `adImpressions`.




## OpenAPI

````yaml GET /api/ad-impressions
openapi: 3.1.0
info:
  title: Verso Fetch API
  version: '2026-09-30'
  description: >
    Read your users' connections and conversations, ingest exports, and delete
    data.


    Every request needs `Authorization: Bearer <API key>`. API keys start with
    `vsk_`

    and are issued at onboarding; several can be active at once so rotation is

    zero-downtime. Using the app secret as a Bearer token still works but is

    deprecated: the app secret is for signing links only.


    The `GET` endpoints are rate limited per app (600 requests per minute by
    default, raised on request) and

    return `RateLimit-*` headers. Errors are JSON objects with a single `error`
    string.
  contact:
    name: Verso
    email: hello@tryverso.ai
servers:
  - url: https://connect.tryverso.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Connections
    description: Per-user connection status and recent activity.
  - name: Conversations
    description: Normalized conversations of a connection.
  - name: Ads
    description: >-
      The ads ChatGPT showed the connected account, with the conversation each
      was shown in.
  - name: Import
    description: Server-side ingestion of a provider export.
  - name: Deletion
    description: GDPR deletion of a user's or a connection's data.
  - name: Native connect
    description: >-
      What the mobile SDKs call to connect from inside an app. Not needed when
      you use an SDK.
paths:
  /api/ad-impressions:
    get:
      tags:
        - Ads
      summary: List the ads an account saw
      description: |
        Returns the ads ChatGPT showed (`viewed`) or the user clicked (`opened`)
        on the connected account, newest first, paginated with `limit` and
        `offset`. The rows come from the account's ads history, which the
        provider keeps for months: they cover conversations from long before
        the user connected. Verso reads the history back to its start over the
        first syncs, then picks up the new impressions at each sync.

        Each impression is matched to the conversation that was open at that
        moment when Verso holds it (`conversationId`, and `messageId` when the
        ad was also read in the conversation). The same rows are listed on each
        conversation as `adImpressions`.
      operationId: listAdImpressions
      parameters:
        - name: connectionId
          in: query
          required: true
          description: >-
            Connection UUID, from `GET /api/connections` or the
            `connection.created` webhook.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          description: >-
            Page size, clamped to 1…500; a missing or unreadable value takes the
            default.
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
        - name: offset
          in: query
          required: false
          description: Number of impressions to skip.
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: One page of impressions.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdImpressionList'
        '400':
          description: '`Missing connectionId parameter`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`Missing Authorization header` or `Invalid API key`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`Connection not found`: unknown id, or a connection of another app.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: '`Could not read the impressions`: a transient read failure, retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RateLimit-Limit:
      description: Requests allowed per minute for your app (600 by default).
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    RateLimit-Reset:
      description: Unix timestamp (seconds) when the current minute ends.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    AdImpressionList:
      type: object
      required:
        - impressions
        - total
        - limit
        - offset
      properties:
        impressions:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/AdImpression'
              - type: object
                required:
                  - conversationId
                properties:
                  conversationId:
                    type:
                      - string
                      - 'null'
                    format: uuid
                    description: |
                      Verso's id of the conversation open when the ad was shown:
                      exact when Verso read the ad in it (`messageId` set),
                      otherwise the conversation active at that moment. Null
                      when none of the imported conversations covers it.
        total:
          type: integer
          description: Impressions of the connection.
          example: 234
        limit:
          type: integer
          example: 100
        offset:
          type: integer
          example: 0
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message. Stable strings, safe to match on.
          example: Connection not found
    AdImpression:
      type: object
      required:
        - id
        - occurredAt
        - action
        - adId
        - advertiser
        - title
        - body
        - url
        - imageUrl
        - messageId
      properties:
        id:
          type: string
          format: uuid
          description: Verso's id for this impression.
        occurredAt:
          type: string
          format: date-time
          description: When the ad was shown or clicked.
        action:
          type: string
          description: >-
            `viewed` when the ad was displayed, `opened` when the user clicked
            it. A click is its own row, next to the `viewed` row of the same
            `adId`.
          example: viewed
        adId:
          type:
            - string
            - 'null'
          description: >-
            The provider's id for the ad request. `ads[].adId` of the same ad on
            the conversation is this id followed by `:<n>`.
          example: 06af3c16-b8df-7e62-8000-d557ca1764a8
        advertiser:
          type: object
          required:
            - id
            - name
            - url
          properties:
            id:
              type:
                - string
                - 'null'
              description: The provider's advertiser account id.
              example: adacct_6aa3f3825760819e8d6230218a087103
            name:
              type:
                - string
                - 'null'
              example: Acme Audio
            url:
              type:
                - string
                - 'null'
              description: The advertiser's site.
              example: https://www.acme-audio.example
        title:
          type:
            - string
            - 'null'
          description: The card's title.
          example: Noise-cancelling headphones
        body:
          type:
            - string
            - 'null'
          description: The card's text.
          example: Over-ear and in-ear models, free returns.
        url:
          type:
            - string
            - 'null'
          description: Landing page, when the ad links to a page.
          example: https://www.acme-audio.example/headphones?utm_source=chatgpt.com
        imageUrl:
          type:
            - string
            - 'null'
          example: https://images.openai.com/…
        messageId:
          type:
            - string
            - 'null'
          description: >-
            `id` of the user message the ad answered, when known: the same ids
            as `payload.messages[].id`.
          example: 5882cd12-a1e6-4a82-9842-a3146f9e7262
  responses:
    RateLimited:
      description: >-
        `Rate limit exceeded`: the app's per-minute allowance (600 by default)
        is used up.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        Your API key (`vsk_…`), issued at onboarding. Keep it server-side.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.