> ## 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.

# Retrieve a session

> Return full sales analysis and tracking context for one session.

Requires `sessions:read`.

Session detail extends the list representation with qualification reasoning,
timeline events, topics, objections, next steps, summary bullets, duration, and
complete attribution context.

For sessions reached through a Custom Link, `lifecycle` contains the observed
Opened, Started, Engaged, lead, and meeting events. This lifecycle is separate
from `timelineEvents`, which remains the conversation-milestone timeline.

Session detail is also the authoritative source for acquisition attribution.
Read `tracking.utmSource`, `tracking.utmCampaign`, `tracking.utmMedium`,
`tracking.utmTerm`, and `tracking.utmContent`. Custom Link and campaign
engagement responses do not aggregate UTM values.

A `404` means the session is unavailable to the key's organization or its
analysis is not available.


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/sessions/{session_id}
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/sessions/{session_id}:
    get:
      tags:
        - Sessions
      summary: Retrieve a session
      description: >-
        Return one analyzed session with qualification, conversation milestones,
        Custom Link lifecycle, topics, objections, tracking, and next steps.
      operationId: v1_get_session
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Session Id
            description: Hobbes session UUID.
          description: Hobbes session UUID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDetailResponse'
          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.
        '404':
          description: >-
            Session not found, outside the key's organization, or not yet
            analyzed.
          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: >-
                      Session not found, outside the key's organization, or not
                      yet analyzed.
        '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:
    SessionDetailResponse:
      properties:
        id:
          type: string
          title: Id
          description: Stable Hobbes session UUID.
          examples:
            - 018f3f6a-0d7b-7f56-bb2a-54c91e57a202
        displayId:
          anyOf:
            - type: string
            - type: 'null'
          title: Displayid
          description: Human-readable session identifier shown in Hobbes.
          examples:
            - SES-1042
        startTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Starttime
          description: Session start time in ISO 8601 format.
          examples:
            - '2026-07-10T18:42:16Z'
        endTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Endtime
          description: Session end time in ISO 8601 format.
          examples:
            - '2026-07-10T18:53:04Z'
        sessionType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sessiontype
          description: Session channel or experience type.
          examples:
            - voice
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Prospect email captured during the session.
          examples:
            - maya@acme.example
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Prospect name captured during the session.
          examples:
            - Maya Chen
        business:
          anyOf:
            - type: string
            - type: 'null'
          title: Business
          description: Prospect company name.
          examples:
            - Acme
        qualificationStatus:
          title: Qualificationstatus
          description: 'Effective person qualification: `qualified` or `unqualified`.'
          examples:
            - qualified
          type: string
          enum:
            - qualified
            - unqualified
          default: unqualified
        buyingIntent:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyingintent
          description: >-
            Detected buying intent. Common values are `high`, `medium`, `low`,
            and `none`.
          examples:
            - high
        bookedStatus:
          anyOf:
            - type: string
            - type: 'null'
          title: Bookedstatus
          description: >-
            Whether the session produced a booking. Common values are `booked`
            and `not_booked`.
          examples:
            - booked
        sessionStatus:
          anyOf:
            - type: string
            - type: 'null'
          title: Sessionstatus
          description: Latest processing or business status for the session.
          examples:
            - completed
        sentiment:
          anyOf:
            - type: string
            - type: 'null'
          title: Sentiment
          description: Overall prospect sentiment detected in the session.
          examples:
            - positive
        engagementLevel:
          anyOf:
            - type: string
            - type: 'null'
          title: Engagementlevel
          description: Detected engagement level.
          examples:
            - high
        primaryIntent:
          anyOf:
            - type: string
            - type: 'null'
          title: Primaryintent
          description: Primary goal inferred from the conversation.
          examples:
            - Evaluate enterprise security
        summaryMarkdown:
          anyOf:
            - type: string
            - type: 'null'
          title: Summarymarkdown
          description: Markdown summary of the session.
          examples:
            - >-
              Maya evaluated Acme's security requirements and booked a technical
              follow-up.
        utmSource:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmsource
          description: Acquisition source captured from UTM parameters.
          examples:
            - linkedin
        device:
          anyOf:
            - type: string
            - type: 'null'
          title: Device
          description: Visitor device category when available.
          examples:
            - desktop
        geoCountry:
          anyOf:
            - type: string
            - type: 'null'
          title: Geocountry
          description: Visitor country when available.
          examples:
            - US
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Prospect phone number when captured.
          examples:
            - +1-415-555-0142
        qualificationReason:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationreason
          description: Why Hobbes assigned the qualification status.
          examples:
            - Confirmed need, authority, and an active evaluation timeline.
        qualificationStage:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationstage
          description: Detected stage of the buying process.
          examples:
            - technical_evaluation
        budgetRange:
          anyOf:
            - type: string
            - type: 'null'
          title: Budgetrange
          description: Budget information expressed by the prospect.
          examples:
            - $25k-$50k annually
        buyingTimeline:
          anyOf:
            - type: string
            - type: 'null'
          title: Buyingtimeline
          description: Expected purchase or evaluation timeline.
          examples:
            - This quarter
        decisionMakerRole:
          anyOf:
            - type: string
            - type: 'null'
          title: Decisionmakerrole
          description: Prospect's role in the decision.
          examples:
            - Technical evaluator
        isDecisionMaker:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Isdecisionmaker
          description: Whether the prospect appears to be a decision-maker.
          examples:
            - false
        confidenceScore:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidencescore
          description: Model confidence from 0 to 1 for the sales analysis.
          examples:
            - 0.91
        nextSteps:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Nextsteps
          description: Recommended or agreed follow-up actions.
          examples:
            - - Send security documentation
              - Prepare technical follow-up
        summaryBullets:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Summarybullets
          description: Concise session takeaways.
          examples:
            - - Evaluating SSO
              - Booked technical follow-up
        audioDurationSeconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Audiodurationseconds
          description: Recorded session duration in seconds.
          examples:
            - 648
        timelineEvents:
          items:
            $ref: '#/components/schemas/TimelineEvent'
          type: array
          title: Timelineevents
          description: Chronological conversation milestones.
        topics:
          items:
            $ref: '#/components/schemas/Topic'
          type: array
          title: Topics
          description: Topics detected during the session.
        objections:
          items:
            $ref: '#/components/schemas/Objection'
          type: array
          title: Objections
          description: Objections detected during the session.
        tracking:
          anyOf:
            - $ref: '#/components/schemas/Tracking'
            - type: 'null'
          description: Acquisition, device, and location context.
        personId:
          anyOf:
            - type: string
            - type: 'null'
          title: Personid
          description: Person UUID associated with the session email.
        qualificationRationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationrationale
          description: >-
            One- or two-sentence rationale for the effective person
            qualification.
        qualificationSource:
          type: string
          enum:
            - automatic
            - manual
          title: Qualificationsource
          description: '`automatic` or `manual`.'
          default: automatic
        qualificationAssessedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Qualificationassessedat
        qualificationRubricVersionId:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationrubricversionid
        overallIntent:
          type: string
          enum:
            - low
            - medium
            - high
          title: Overallintent
          description: Recency- and frequency-weighted intent across the person's sessions.
          default: low
        intentScore:
          type: number
          maximum: 3
          minimum: 0
          title: Intentscore
          default: 0
        intentCalculatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Intentcalculatedat
        customLinkId:
          anyOf:
            - type: string
            - type: 'null'
          title: Customlinkid
          description: Custom Link associated with this session.
        customLinkCampaignId:
          anyOf:
            - type: string
            - type: 'null'
          title: Customlinkcampaignid
          description: Custom Link campaign associated with this session.
        lifecycle:
          anyOf:
            - $ref: '#/components/schemas/SessionLifecycle'
            - type: 'null'
          description: >-
            Observed Custom Link lifecycle. Separate from conversation
            timelineEvents.
      type: object
      required:
        - id
      title: SessionDetailResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TimelineEvent:
      properties:
        milestoneType:
          anyOf:
            - type: string
            - type: 'null'
          title: Milestonetype
          description: Type of conversation milestone.
          examples:
            - feature_discussion
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Plain-language milestone description.
          examples:
            - Asked about CRM synchronization.
        timestampOffsetS:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timestampoffsets
          description: Seconds from the beginning of the session.
          examples:
            - 184
        featuresMentioned:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Featuresmentioned
          description: Hobbes or customer product features discussed.
          examples:
            - - CRM sync
              - lead routing
        sequenceOrder:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sequenceorder
          description: Stable chronological order within the timeline.
          examples:
            - 3
      type: object
      title: TimelineEvent
    Topic:
      properties:
        topic:
          anyOf:
            - type: string
            - type: 'null'
          title: Topic
          description: Topic discussed during the session.
          examples:
            - Security review
        interestLevel:
          anyOf:
            - type: string
            - type: 'null'
          title: Interestlevel
          description: Detected prospect interest in the topic.
          examples:
            - high
        timeDiscussedS:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timediscusseds
          description: Approximate seconds spent on the topic.
          examples:
            - 142
        outcome:
          anyOf:
            - type: string
            - type: 'null'
          title: Outcome
          description: Outcome of the topic discussion.
          examples:
            - Requested technical documentation
      type: object
      title: Topic
    Objection:
      properties:
        objectionType:
          anyOf:
            - type: string
            - type: 'null'
          title: Objectiontype
          description: Category of the detected objection.
          examples:
            - security
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Prospect's objection in plain language.
          examples:
            - Needs confirmation of SSO support.
        severity:
          anyOf:
            - type: string
            - type: 'null'
          title: Severity
          description: Detected objection severity.
          examples:
            - medium
        handled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Handled
          description: Whether the conversation addressed the objection.
          examples:
            - true
        resolutionNotes:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolutionnotes
          description: How the objection was addressed.
          examples:
            - Confirmed SAML SSO availability.
        timestampOffsetS:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timestampoffsets
          description: Seconds from the beginning of the session.
          examples:
            - 376
      type: object
      title: Objection
    Tracking:
      properties:
        utmSource:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmsource
          description: UTM source.
          examples:
            - linkedin
        utmMedium:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmmedium
          description: UTM medium.
          examples:
            - paid-social
        utmCampaign:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmcampaign
          description: UTM campaign.
          examples:
            - enterprise-q3
        utmTerm:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmterm
          description: UTM term.
          examples:
            - ai-demo
        utmContent:
          anyOf:
            - type: string
            - type: 'null'
          title: Utmcontent
          description: UTM content value.
          examples:
            - security-ad
        referrerUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Referrerurl
          description: Referring page URL.
          examples:
            - https://www.linkedin.com/
        landingPageUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Landingpageurl
          description: First page visited in the session.
          examples:
            - https://acme.example/demo
        device:
          anyOf:
            - type: string
            - type: 'null'
          title: Device
          description: Visitor device category.
          examples:
            - desktop
        browser:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser
          description: Visitor browser.
          examples:
            - Chrome
        os:
          anyOf:
            - type: string
            - type: 'null'
          title: Os
          description: Visitor operating system.
          examples:
            - macOS
        geoCountry:
          anyOf:
            - type: string
            - type: 'null'
          title: Geocountry
          description: Visitor country code.
          examples:
            - US
        geoRegion:
          anyOf:
            - type: string
            - type: 'null'
          title: Georegion
          description: Visitor region when available.
          examples:
            - California
        geoCity:
          anyOf:
            - type: string
            - type: 'null'
          title: Geocity
          description: Visitor city when available.
          examples:
            - San Francisco
      type: object
      title: Tracking
    SessionLifecycle:
      properties:
        stage:
          type: string
          enum:
            - not_opened
            - opened
            - started
            - engaged
          title: Stage
        events:
          items:
            $ref: '#/components/schemas/SessionLifecycleEvent'
          type: array
          title: Events
      type: object
      required:
        - stage
      title: SessionLifecycle
    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
    SessionLifecycleEvent:
      properties:
        eventType:
          type: string
          enum:
            - opened
            - started
            - engaged
            - lead_submitted
            - meeting_clicked
            - meeting_booked
          title: Eventtype
        observedAt:
          type: string
          format: date-time
          title: Observedat
      type: object
      required:
        - eventType
        - observedAt
      title: SessionLifecycleEvent
  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.

````