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

# List conversation history

> Calls and assistant email conversations in your workspace, globally sorted by latest activity. Failed outbound call rows include the provider-neutral `failure` object. Every inbound and outbound email turn with the same stable `thread_id` is grouped into one conversation row. Email reply states are normalized to the shared statuses (`pending` → `in_progress`, `replied`/outbound → `completed`). **Required scope:** `calls:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /history
openapi: 3.1.0
info:
  title: OurAiCalling API
  version: 1.0.0
  description: >-
    REST API for OurAiCalling. Authenticate with an API key (`fam_...`, created
    under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`)
    as a Bearer token.


    Every response uses a consistent envelope: `{ "data": ... , "meta": { ... }
    }` on success and `{ "error": { "code", "message" } }` on failure. List
    endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`;
    `meta.pagination.total` carries the total match count.


    Everything documented here is also exposed as MCP tools at
    `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using
    the same credentials and permission model.
servers:
  - url: https://app.famulor.io/api/v1
    description: Hosted platform.
  - url: https://{domain}/api/v1
    description: White-label tenant domain — same paths, tenant branding.
    variables:
      domain:
        default: app.famulor.io
        description: Your white-label tenant domain.
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Self-inspection of the calling credential.
  - name: Migrations
    description: Preview and import data from supported legacy platforms.
  - name: Assistants
    description: Create and manage voice assistants.
  - name: Tools
    description: >-
      Reusable tools (HTTP APIs and external MCP servers) assistants can call
      mid-conversation.
  - name: Voices
    description: Browse the text-to-speech voice library.
  - name: Calls
    description: Start outbound calls and read call history, transcripts and recordings.
  - name: History
    description: Unified conversation history across calls, messaging and assistant emails.
  - name: Campaigns
    description: Outbound calling campaigns with a compliant power dialer.
  - name: Leads
    description: Manage Audience contacts across campaigns, channels and Call QA metrics.
  - name: Segments
    description: >-
      Saved, dynamic lead filters — reusable audience definitions used for
      Audience search and campaign lead assignment.
  - name: Suppression
    description: Cross-channel marketing opt-outs and active workspace suppression records.
  - name: Callbacks
    description: >-
      Scheduled callbacks booked by the Schedule callback tool across voice,
      chat, and email.
  - name: Phone Numbers
    description: Marketplace numbers and customer-provided numbers.
  - name: SIP Trunks
    description: Bring your own SIP provider and numbers.
  - name: Carrier Connections
    description: Connect a supported carrier account and import its existing phone numbers.
  - name: Knowledge Bases
    description: RAG knowledge bases and documents for assistants.
  - name: Settings
    description: Workspace-level settings such as caller-memory defaults.
  - name: Billing
    description: Balance and minutes ledger of the key owner.
  - name: Automations
    description: >-
      Native workspace automations — list, create, update, trigger. Plan gate:
      automation_platform.
  - name: Integrations
    description: >-
      Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google
      Calendar, Outlook, native booking engine). Assign them to assistants to
      provide availability and booking tools, plus provider-supported
      appointment lookup, cancellation, and rescheduling.
  - name: Bookings
    description: >-
      Native booking engine — event types with weekly availability, public
      booking pages at /book/{workspace}/{slug}, and the bookings they produce.
  - name: Dashboards
    description: >-
      Custom analytics dashboards, reusable widgets, and tenant-scoped
      performance analytics. Requires the custom_dashboards plan feature.
  - name: Catalog
    description: >-
      Read-only platform catalogs — available models, supported assistant
      languages, and prompt templates.
  - name: Simulations
    description: Assistant simulation tests (plan-gated).
  - name: Versions
    description: Assistant configuration version history.
  - name: Caller IDs
    description: Outbound caller ID verification.
  - name: Widgets
    description: Web widget connectors.
  - name: Messaging
    description: >-
      Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK).
      Includes conversation delay, inactivity end, and conversation-ended
      webhooks.
  - name: QA
    description: Cohort AI Quality Assurance runs over call transcripts.
  - name: White Label
    description: >-
      Manage the customers of your white-label workspace on their behalf — list,
      register, mint access tokens, log in, log out, and transfer credits.
      Available to reseller workspaces with white-label access, and to platform
      admins (scoped to direct platform customers). Requires `platform:read` /
      `platform:write`.
  - name: API Keys
    description: >-
      Self-service API keys for the calling workspace. A key can only mint
      further keys with a scope subset of its own.
  - name: SMS
    description: Outbound SMS from workspace phone numbers.
paths:
  /history:
    get:
      tags:
        - History
      summary: List conversation history
      description: >-
        Calls and assistant email conversations in your workspace, globally
        sorted by latest activity. Failed outbound call rows include the
        provider-neutral `failure` object. Every inbound and outbound email turn
        with the same stable `thread_id` is grouped into one conversation row.
        Email reply states are normalized to the shared statuses (`pending` →
        `in_progress`, `replied`/outbound → `completed`). **Required scope:**
        `calls:read`.
      operationId: listHistory
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - call
              - avatar
              - email
              - live_chat
              - whatsapp_voice
              - whatsapp
              - telegram
              - slack
              - messenger
              - teams
              - discord
              - gchat
              - x
          description: >-
            Filter by conversation type. `avatar` = web voice with virtual
            avatar; `live_chat` = widget text chat; messaging platforms query
            messaging conversations.
        - name: direction
          in: query
          schema:
            type: string
            enum:
              - inbound
              - outbound
              - web
          description: Filter by direction. `web` applies only to calls.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - queued
              - ringing
              - in_progress
              - completed
              - failed
              - no_answer
              - busy
              - skipped
        - name: assistant_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter calls and emails by assistant.
        - name: campaign_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by campaign; campaign history contains calls only.
        - name: lead_id
          in: query
          schema:
            type: string
            format: uuid
          description: >-
            Filter the unified history by one Audience contact across calls,
            messaging and email.
        - name: search
          in: query
          schema:
            type: string
          description: >-
            Search phone numbers, email addresses, email subject/body, and call
            summaries.
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Only entries active at or after this ISO 8601 date/datetime (latest
            message time for email threads).
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Only entries active at or before this ISO 8601 date/datetime (latest
            message time for email threads).
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A globally sorted page of calls and emails.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoryItem'
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          limit:
                            type: integer
                          offset:
                            type: integer
                          total:
                            type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
      description: Page size (1–200).
    offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of items to skip.
  schemas:
    HistoryItem:
      type: object
      required:
        - id
        - thread_id
        - channel
        - direction
        - assistant_id
        - assistant_name
        - status
        - contact
        - from
        - to
        - subject
        - body_preview
        - summary
        - duration_sec
        - campaign_id
        - reply_status
        - reply_error
        - attachments_count
        - message_count
        - created_at
        - last_activity_at
      properties:
        id:
          type: string
          format: uuid
        thread_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Stable email or messaging conversation ID; null for calls.
        lead_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Canonical Audience contact relation.
        channel:
          type: string
          enum:
            - call
            - avatar
            - email
            - live_chat
            - whatsapp_voice
            - whatsapp
            - telegram
            - slack
            - messenger
            - teams
            - discord
            - gchat
            - x
        direction:
          type: string
          enum:
            - inbound
            - outbound
            - web
        assistant_id:
          type:
            - string
            - 'null'
          format: uuid
        assistant_name:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - queued
            - ringing
            - in_progress
            - completed
            - failed
            - no_answer
            - busy
            - skipped
        failure:
          $ref: '#/components/schemas/PublicCallFailure'
          description: >-
            Provider-neutral failure guidance. Present only when a call-row
            conversation has a normalized outbound failure.
        contact:
          type:
            - string
            - 'null'
          description: External phone number or email address.
        from:
          type:
            - string
            - 'null'
        to:
          type:
            - string
            - 'null'
        subject:
          type:
            - string
            - 'null'
          description: Email subject; null for calls.
        body_preview:
          type:
            - string
            - 'null'
          description: Compact plain-text email preview; null for calls.
        summary:
          type:
            - string
            - 'null'
          description: Call summary or email subject/body preview.
        duration_sec:
          type:
            - integer
            - 'null'
          description: Call duration; null for emails.
        campaign_id:
          type:
            - string
            - 'null'
          format: uuid
        reply_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - replied
            - skipped
            - failed
            - null
          description: >-
            Raw auto-reply state for inbound emails; null for calls and outbound
            email rows.
        reply_error:
          type:
            - string
            - 'null'
        attachments_count:
          type: integer
          minimum: 0
        message_count:
          type: integer
          minimum: 1
          description: All inbound and outbound messages grouped into this conversation.
        created_at:
          type: string
          format: date-time
        last_activity_at:
          type: string
          format: date-time
          description: >-
            Latest message time for email threads; equal to created_at for
            calls.
    PublicCallFailure:
      type: object
      additionalProperties: false
      required:
        - domain
        - code
        - message
        - retryable
        - action
      description: >-
        Provider-neutral failure guidance for calls. Telephony failures also set
        operation.
      properties:
        domain:
          type: string
          enum:
            - telephony
            - billing
            - admission
            - runtime
            - config
            - dispatch
            - workspace
        operation:
          type: string
          enum:
            - outbound_call
            - cold_transfer
            - warm_transfer
          description: Present when domain is telephony.
        code:
          type: string
          enum:
            - busy
            - declined
            - no_answer
            - temporarily_unavailable
            - cancelled_before_answer
            - invalid_destination
            - destination_not_found
            - authentication_failed
            - destination_forbidden
            - trunk_unavailable
            - no_outbound_trunk
            - transfer_unavailable
            - unknown
            - insufficient_credits
            - reservation_failed
            - outbound_quota_reservation_failed
            - integrated_outbound_limit_reached
            - quiet_hours
            - budget_service_unavailable
            - workspace_concurrency_limit
            - campaign_concurrency_limit
            - platform_unavailable
            - region_unavailable
            - capability_unavailable
            - capacity_exhausted
            - admission_unavailable
            - voice_unavailable
            - speech_unavailable
            - assistant_unavailable
            - call_runtime_failed
            - workspace_suspended
            - dispatch_failed
            - missing_destination
        message:
          type: string
          description: Stable, provider-neutral English explanation.
        retryable:
          type: boolean
          description: >-
            Informational retry guidance. It does not change campaign retry
            policy.
        action:
          type: string
          enum:
            - retry_later
            - do_not_retry
            - check_destination
            - check_trunk_credentials
            - check_trunk_configuration
            - connect_outbound_number
            - continue_call
            - contact_support
            - top_up
            - check_assistant
            - check_campaign_schedule
    ErrorEnvelope:
      type: object
      description: Error envelope returned by every /api/v1 endpoint on failure.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - not_found
                - invalid_request
                - rate_limited
                - conflict
                - telephony_configuration_error
                - telephony_unavailable
                - internal_error
              description: Stable, machine-readable error code.
            message:
              type: string
              description: Human-readable description of the error.
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: invalid_request
              message: '"to_number" is required (E.164 format, e.g. +4930123456).'
    Unauthorized:
      description: Missing, invalid, expired or revoked API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: unauthorized
              message: Invalid API key.
    Forbidden:
      description: >-
        The API key lacks the required scope, or the plan does not allow this
        action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: forbidden
              message: This API key is missing the required scope "assistants:write".
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        API key (`fam_...`, created under **Settings → API Keys**) or an OAuth
        2.0 access token (`fam_at_...`). Keys can be restricted to scopes such
        as `assistants:read`, `calls:write`, `campaigns:write`,
        `automations:read`, `dashboards:read`, `dashboards:write`,
        `leads:write`, `segments:write`, `phone_numbers:write`,
        `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`,
        `settings:write`, `platform:read`, `platform:write`; a `*:write` scope
        implies the matching `*:read`. Automation and dashboard endpoints also
        accept the legacy `calls:*` scope. Keys without scope restrictions have
        full access.

````