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

# List Custom Links

> Return a filterable, paginated list of Custom Links.

Requires `custom_links:read` or `custom_links:write`.

Filter by campaign, active status, engagement stage, external id, email,
company, creation date, or search text. Sort by creation time or latest
activity. Results include the published URL, thumbnail state, and engagement
rollup.

`loadCount` counts accepted non-bot load events; `pageViewCount` deduplicates
them by page-view id. `uniqueVisitorCount` uses persistent anonymous browser
continuity where storage is available and includes ephemeral page views as an
estimate where it is not. Check `visitorCountMode` before interpreting the
total. When it is `estimated`, `loadsPerUniqueVisitor` is approximate.
`persistentUniqueVisitorCount` and `ephemeralPageViewCount` expose the exact
coverage inputs. `loadsPerUniqueVisitor` is null until at least one visitor is
observed.


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/custom-links
openapi: 3.1.0
info:
  title: Hobbes API
  description: >

    Use the Hobbes API to read your organization's analyzed demo sessions,

    prospects, accounts, transcripts, and funnel metrics, and to create and
    manage

    personalized Custom Links.


    **Authentication**: create an API key in Settings → API Keys, then send it

    as `Authorization: Bearer <key>` (or `x-api-key: <key>`). Keys are

    org-scoped; responses only ever contain your organization's data.


    **Scopes**: keys carry scopes (`sessions:read`, `people:read`,

    `accounts:read`, `analytics:read`, `transcripts:read`, `custom_links:read`,

    `custom_links:write`). `custom_links:write` also satisfies read access. Raw

    transcript access is a separate opt-in scope with a daily quota. Existing
    API

    keys do not receive Custom Link scopes automatically.


    **Rate limits**: keys allow 120 requests per minute by default. Responses

    include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 responses
    include

    `Retry-After`. Transcript access has a separate quota of 2,000 reads per

    organization per UTC day. Custom Link mutations are limited to 10 requests
    per

    minute per organization. Creation and thumbnail rendering also use weighted

    hourly and daily organization quotas, so one request containing 500 links is

    one HTTP request but consumes up to 500 creation and 500 render units.


    **Support**: every response carries an `X-Request-ID` header. Include it
    when

    reporting an issue so we can find the exact request in our logs.


    **Stability**: changes within v1 are additive only. Fields may be added to

    responses; existing fields are never removed or renamed.
  version: 1.0.0
servers:
  - url: https://api-us.hihobbes.com
    description: Production
security:
  - bearer: []
  - apiKeyHeader: []
tags:
  - name: Sessions
    description: Analyzed demo sessions and their transcripts.
  - name: People
    description: Prospect profiles aggregated across sessions.
  - name: Accounts
    description: Company-level engagement rollups by email domain.
  - name: Metrics
    description: Aggregate funnel performance over a trailing window.
  - name: Custom Links
    description: Create and manage personalized links.
  - name: Custom Link Jobs
    description: Poll, cancel, and retry asynchronous Custom Link work.
  - name: Custom Link Campaigns
    description: Organize Custom Links into campaigns.
paths:
  /api/v1/custom-links:
    get:
      tags:
        - Custom Links
      summary: List Custom Links
      description: >-
        Return a paginated, filterable list of Custom Links in the key's
        organization.
      operationId: v1_list_custom_links
      parameters:
        - name: campaign_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Campaign Id
            description: Custom Link campaign UUID.
          description: Custom Link campaign UUID.
        - name: active
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Active
        - name: external_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            title: External Id
        - name: email
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            title: Email
            description: Exact prospect email address. URL-encode reserved characters.
          description: Exact prospect email address. URL-encode reserved characters.
        - name: company
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            title: Company
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            title: Search
        - name: date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Date From
        - name: date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Date To
        - name: engagement_stage
          in: query
          required: false
          schema:
            title: Engagement Stage
            description: >-
              Filter Custom Links by their monotonic not_opened, opened,
              started, or engaged stage.
            anyOf:
              - $ref: '#/components/schemas/EngagementStage'
              - type: 'null'
          description: >-
            Filter Custom Links by their monotonic not_opened, opened, started,
            or engaged stage.
        - name: sort
          in: query
          required: false
          schema:
            type: string
            default: created_at
            title: Sort
            description: Sort by created_at or last_activity_at.
            enum:
              - created_at
              - last_activity_at
          description: Sort by created_at or last_activity_at.
        - name: order
          in: query
          required: false
          schema:
            enum:
              - asc
              - desc
            type: string
            default: desc
            title: Order
            description: 'Sort direction: asc or desc.'
          description: 'Sort direction: asc or desc.'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            default: 50
            title: Limit
            description: Number of records to return. Defaults to 50 and cannot exceed 200.
          description: Number of records to return. Defaults to 50 and cannot exceed 200.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000000
            minimum: 0
            default: 0
            title: Offset
            description: >-
              Zero-based number of records to skip. Use with `pagination.total`
              to request the next page.
          description: >-
            Zero-based number of records to skip. Use with `pagination.total` to
            request the next page.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLinksListResponse'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
        '401':
          description: API key required or invalid.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key required or invalid.
        '403':
          description: API key does not include the required scope.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key does not include the required scope.
        '422':
          description: A path, query, header, or request field failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
        '429':
          description: Rate limit or organization quota exceeded.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Rate limit or organization quota exceeded.
components:
  schemas:
    EngagementStage:
      type: string
      enum:
        - not_opened
        - opened
        - started
        - engaged
      title: EngagementStage
    CustomLinksListResponse:
      properties:
        customLinks:
          items:
            $ref: '#/components/schemas/CustomLinkResponse'
          type: array
          title: Customlinks
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
        - customLinks
        - total
        - limit
        - offset
      title: CustomLinksListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CustomLinkResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        externalId:
          anyOf:
            - type: string
            - type: 'null'
          title: Externalid
        displayName:
          type: string
          title: Displayname
        firstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Firstname
        lastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastname
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
        shareTitle:
          anyOf:
            - type: string
            - type: 'null'
          title: Sharetitle
        shareDescription:
          anyOf:
            - type: string
            - type: 'null'
          title: Sharedescription
        shareThumbnailUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sharethumbnailurl
        prospectLogoUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Prospectlogourl
        prospectDomain:
          anyOf:
            - type: string
            - type: 'null'
          title: Prospectdomain
        active:
          type: boolean
          title: Active
        campaignId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Campaignid
        jobId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Jobid
        url:
          type: string
          title: Url
        thumbnailStatus:
          type: string
          enum:
            - not_requested
            - provided
            - queued
            - processing
            - generated
            - fallback
            - failed
            - cancelled
          title: Thumbnailstatus
        thumbnailAttempts:
          type: integer
          title: Thumbnailattempts
          default: 0
        thumbnailError:
          anyOf:
            - $ref: '#/components/schemas/CustomLinkError'
            - type: 'null'
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        engagement:
          $ref: '#/components/schemas/CustomLinkEngagement'
      type: object
      required:
        - id
        - displayName
        - active
        - url
        - thumbnailStatus
        - engagement
        - createdAt
        - updatedAt
      title: CustomLinkResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    CustomLinkError:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: CustomLinkError
    CustomLinkEngagement:
      properties:
        stage:
          $ref: '#/components/schemas/EngagementStage'
        openObserved:
          type: boolean
          title: Openobserved
        botScannedOnly:
          type: boolean
          title: Botscannedonly
        pageViewCount:
          type: integer
          title: Pageviewcount
        uniqueVisitorCount:
          type: integer
          title: Uniquevisitorcount
        persistentUniqueVisitorCount:
          type: integer
          title: Persistentuniquevisitorcount
        ephemeralPageViewCount:
          type: integer
          title: Ephemeralpageviewcount
        loadsPerUniqueVisitor:
          anyOf:
            - type: number
            - type: 'null'
          title: Loadsperuniquevisitor
        firstOpenedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstopenedat
        lastOpenedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Lastopenedat
        sessionCount:
          type: integer
          title: Sessioncount
        startedSessionCount:
          type: integer
          title: Startedsessioncount
        engagedSessionCount:
          type: integer
          title: Engagedsessioncount
        leadSubmitted:
          type: boolean
          title: Leadsubmitted
        meetingClicked:
          type: boolean
          title: Meetingclicked
        meetingBooked:
          type: boolean
          title: Meetingbooked
        lastActivityAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Lastactivityat
        lastActivityType:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastactivitytype
        firstStartedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firststartedat
        firstEngagedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstengagedat
        firstLeadSubmittedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstleadsubmittedat
        firstMeetingClickedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstmeetingclickedat
        firstMeetingBookedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstmeetingbookedat
        loadCount:
          type: integer
          title: Loadcount
        visitorCountMode:
          $ref: '#/components/schemas/VisitorCountMode'
      type: object
      title: CustomLinkEngagement
      required:
        - stage
        - openObserved
        - botScannedOnly
        - loadCount
        - pageViewCount
        - uniqueVisitorCount
        - persistentUniqueVisitorCount
        - ephemeralPageViewCount
        - loadsPerUniqueVisitor
        - visitorCountMode
        - firstOpenedAt
        - lastOpenedAt
        - firstStartedAt
        - firstEngagedAt
        - firstLeadSubmittedAt
        - firstMeetingClickedAt
        - firstMeetingBookedAt
        - sessionCount
        - startedSessionCount
        - engagedSessionCount
        - leadSubmitted
        - meetingClicked
        - meetingBooked
        - lastActivityAt
        - lastActivityType
    VisitorCountMode:
      type: string
      enum:
        - identified
        - estimated
      title: VisitorCountMode
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Hobbes API key with the `hb_live_` prefix.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Bearer authorization header.

````