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

# Get Call



## OpenAPI

````yaml GET /calls/{id}
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /calls/{id}:
    get:
      tags:
        - Calls
      summary: Get call
      operationId: getCall
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Full call details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  agent_id:
                    type: string
                    format: uuid
                  from:
                    type: string
                  to:
                    type: string
                  direction:
                    type: string
                  status:
                    type: string
                  started_at:
                    type: string
                    format: date-time
                    nullable: true
                  ended_at:
                    type: string
                    format: date-time
                    nullable: true
                  duration_seconds:
                    type: integer
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                    description: >-
                      The metadata object you attached at `POST /calls`. Empty
                      object `{}` if no metadata was provided at call creation.
                  created_at:
                    type: string
                    format: date-time
                  ended_by:
                    type: string
                    enum:
                      - caller
                      - agent
                      - system
                      - unknown
                    nullable: true
                    description: >-
                      Who terminated the call. First-write-wins (a specific
                      value like 'system' from voicemail detection is not
                      overwritten by a later generic 'caller').
                  disconnect_reason:
                    type: string
                    nullable: true
                    description: >-
                      User-friendly reason the call ended (e.g. 'Completed',
                      'Voicemail detected'). First-write-wins.
                  transferred_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: >-
                      When the call was transferred (set only if
                      status='transferred').
                  transfer_target:
                    type: string
                    nullable: true
                    description: E.164 number or SIP URI the call was transferred to.
                  recording_url:
                    type: string
                    nullable: true
                    description: >-
                      Permanent signed URL for the call recording. Opens
                      directly in a browser or audio player — redirects (302) to
                      the audio file. No additional authentication required.
                  disposition:
                    nullable: true
                    description: >-
                      Full Disposition object. Present only when a disposition
                      has been assigned.
                    allOf:
                      - $ref: '#/components/schemas/Disposition'
                  lead:
                    nullable: true
                    description: >-
                      Full Lead object including long_term_context and tags.
                      Present only when a matched lead exists.
                    allOf:
                      - $ref: '#/components/schemas/Lead'
                  summary:
                    type: string
                    description: AI-generated call summary. Present only when available.
                    nullable: true
                  transcript:
                    type: array
                    description: >-
                      Full call transcript, ordered by time. Present only when
                      available.
                    items:
                      $ref: '#/components/schemas/TranscriptEntry'
                  extracted_data:
                    type: object
                    description: >-
                      Structured fields extracted post-call by the agent's
                      extraction_parameters. Present only when extraction ran
                      and produced at least one value.
                  tool_calls:
                    type: array
                    description: >-
                      Paired request/response objects for each tool invocation
                      during the call. Easier to consume than raw events.
                      Auth-related headers (Authorization, tokens, keys) are
                      redacted as `[REDACTED]`.
                    items:
                      $ref: '#/components/schemas/ToolCallPair'
                  events:
                    type: array
                    description: >-
                      Full ordered event stream for the call. Low-level — for
                      flow agents prefer `flow_trace` (below). Auth headers in
                      `tool_called` events are redacted.
                    items:
                      $ref: '#/components/schemas/CallEvent'
                  flow_trace:
                    nullable: true
                    description: >
                      **Present only on flow-agent calls**
                      (`agent.type='flow'`). For prompt agents this field is
                      omitted.

                      Structured view of the call's path through the flow graph,
                      built from the underlying `flow_*` events.

                      For flow agents `tool_calls[]` is always empty — flow tool
                      nodes use a separate dispatch path that

                      emits `flow_tool_result` events (surfaced inline on each
                      `flow_trace.steps[].tool_call`).
                    allOf:
                      - $ref: '#/components/schemas/FlowTrace'
        '404':
          description: Not found
components:
  schemas:
    Disposition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        color:
          type: string
          nullable: true
          example: '#22c55e'
        position:
          type: integer
        is_protected:
          type: boolean
          description: Protected dispositions cannot be deleted.
        created_at:
          type: string
          format: date-time
    Lead:
      type: object
      properties:
        id:
          type: string
          format: uuid
        phone_number:
          type: string
          example: '+972501234567'
        name:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        source:
          type: string
          example: api
          description: >-
            How the lead was created: 'api', 'manual', or 'auto' (from inbound
            call).
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LeadTag'
        long_term_context:
          type: string
          nullable: true
          description: >-
            AI memory for this lead. Injected into the agent's system prompt at
            call time when lead_memory_enabled is true on the agent.
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TranscriptEntry:
      type: object
      description: A single turn in a call transcript.
      required:
        - role
        - text
        - start
        - end
      properties:
        role:
          type: string
          enum:
            - agent
            - user
            - voicemail
          description: >
            Who is speaking. `agent` — the AI agent. `user` — the live human on
            the call. `voicemail` — pre-recorded audio from the callee's
            answering machine, carrier voicemail greeting, or IVR menu. Treat
            these entries as non-conversational: they represent the callee's
            voicemail system, not anything the person actually said. When any
            entry has `role: "voicemail"`, the call's disposition will be
            `Voicemail`.
        text:
          type: string
          description: Transcribed speech in the call's original language.
        start:
          type: integer
          description: Milliseconds from recording start.
        end:
          type: integer
          description: Milliseconds from recording start.
    ToolCallPair:
      type: object
      description: >
        A single tool invocation (request + response) extracted from the call's
        event stream. The list

        contains both prompt-mode webhook tools and flow-mode
        tool/integration_call fires, in firing order.

        `kind` is the discriminator:


        - `webhook_tool` — prompt-mode agents with a tool list. Built from
        paired `tool_called` /
          `tool_response` events. The `request` envelope carries the full HTTP request (method, url,
          headers, body).
        - `tool_call` — flow-mode `tool_call` node fired. Built from one
        `flow_tool_result` event.
          `request` carries just `body` (the resolved args dict); HTTP details aren't meaningful here.
        - `integration_call` — flow-mode `integration_call` node fired (Google
        Calendar / Gmail / etc.).
          Same `request.body`-only shape as `tool_call`; sibling fields `provider`, `action`,
          `integration_id` identify which connected credential and method ran.

        For flow agents prefer `flow_trace.steps[].tool_call` — same data,
        inlined per visited step.
      required:
        - tool_name
        - timestamp
        - kind
      properties:
        tool_name:
          type: string
        timestamp:
          type: string
          format: date-time
        kind:
          type: string
          enum:
            - webhook_tool
            - tool_call
            - integration_call
        node:
          type: object
          nullable: true
          description: >-
            Flow node identity. Set when `kind` is `tool_call` or
            `integration_call`; null for `webhook_tool`.
          properties:
            id:
              type: string
            name:
              type: string
            type:
              type: string
              enum:
                - tool_call
                - integration_call
        tool_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Set when `kind` is `webhook_tool` or `tool_call`. References the
            tools table row.
        provider:
          type: string
          nullable: true
          description: Set when `kind=integration_call` (e.g. `google_calendar`).
        action:
          type: string
          nullable: true
          description: Set when `kind=integration_call` (e.g. `create_event`).
        integration_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Set when `kind=integration_call`. Connected credential used for this
            fire.
        arg_sources:
          type: object
          nullable: true
          additionalProperties:
            type: string
            enum:
              - literal
              - ai_extract
          description: >-
            Per-arg provenance map. Set for flow-mode rows; null for
            `webhook_tool`.
        request:
          type: object
          required:
            - body
          properties:
            method:
              type: string
              nullable: true
              description: Set only when `kind=webhook_tool`.
            url:
              type: string
              nullable: true
              description: Set only when `kind=webhook_tool`.
            headers:
              type: object
              additionalProperties:
                type: string
              description: >-
                Set only when `kind=webhook_tool`. Auth-related keys
                (Authorization, tokens, API keys) are redacted as `[REDACTED]`.
            body:
              description: >-
                Rendered request body / args dict sent to the tool or
                integration.
              nullable: true
        response:
          type: object
          nullable: true
          properties:
            success:
              type: boolean
              nullable: true
            response_preview:
              type: string
              nullable: true
              description: JSON-stringified result the LLM saw, truncated to ~50KB.
            raw_response_preview:
              type: string
              nullable: true
              description: >-
                Provider's untouched payload, present only when the LLM-facing
                sanitized view differs from the raw API response (e.g. Google
                Calendar dateTime stripping). Useful for audit.
            error:
              type: string
              nullable: true
            duration_ms:
              type: integer
              nullable: true
    CallEvent:
      type: object
      description: >
        A single event from a call's lifecycle, returned in the `events[]` array
        of `GET /calls/{id}`.

        Events are ordered by `timestamp` ascending. Use these for granular
        timing analysis and — for

        flow agents — reconstructing the decision path through the graph.
      required:
        - type
        - timestamp
        - data
      properties:
        type:
          type: string
          enum:
            - call_initiated
            - websocket_connected
            - webrtc_connected
            - llm_started
            - llm_response_started
            - llm_response_ended
            - tool_called
            - tool_response
            - transcription_user
            - transcription_agent
            - call_ended
            - call_ended_idle
            - call_ended_max_duration
            - error
            - flow_started
            - flow_node_entered
            - flow_eval_decision
            - flow_tool_result
          description: >
            Event type. Standard call lifecycle events fire on every call.

            `flow_*` events fire only on flow agents (`agent.type='flow'`):


            - `flow_started` — flow controller began. `data`: `{agent_id,
            first_step_id, agent_speaks_first}`

            - `flow_node_entered` — a node was entered. `data`: `{step_id, type,
            name, reason}`
              The `reason` string explains routing (e.g. "tool success", "tool custom: Already booked",
              "eval: agreed_to_demo", "tool error: HTTP 500: ...").
            - `flow_eval_decision` — the model picked a transition for a
            conversation node.
              `data`: `{step_id, decision, valid, target_step_id, reason, reasoning, turn_id}`.
              `step_id` — node the decision was made FROM.
              `decision` — the transition id picked (or `"stay"`).
              `valid` — boolean; whether the picked transition was accepted.
              `target_step_id` — destination step id when `valid` is true; null otherwise.
              `reason` — short status/error explanation (e.g. why the pick was rejected).
              `reasoning` — the model's short justification for the pick.
              `turn_id` — monotonic counter for the conversation turn the decision ran on.
            - `flow_tool_result` — a tool_call or integration_call node
            finished. `data`: `{step_id,
              kind, status, tool_name, tool_id, provider, integration_id, action, args, arg_sources,
              response_preview, raw_response_preview, error, duration_ms}`. `kind` is `"tool_call"` |
              `"integration_call"`. `status` is `"success"` | `"error"`.
              `response_preview` is the JSON-stringified result the LLM saw (truncated to 50KB).
              `raw_response_preview` is present when the provider did server-side post-processing
              for the LLM (currently: Google Calendar wall-clock conversion); it carries the
              untouched provider response for audit. Null when `result` and `raw` are identical.
        timestamp:
          type: string
          format: date-time
        data:
          type: object
          description: >-
            Event-specific payload. Shape depends on `type`. Auth-related
            headers in `tool_called` events are redacted as `[REDACTED]`.
    FlowTrace:
      type: object
      description: >
        Structured view of a flow agent's path through its graph during the
        call. Built from the

        underlying `flow_started` / `flow_node_entered` / `flow_eval_decision` /
        `flow_tool_result` events.


        **Use this instead of `events[]` and `tool_calls[]` when working with
        flow-agent calls** — it gives

        you the ordered list of nodes visited, why each transition happened, the
        eval-LLM's reasoning at

        each conversation node, and the tool I/O inlined per step.
      required:
        - started_at
        - steps
      properties:
        started_at:
          type: string
          format: date-time
          description: When the flow controller started for this call.
        agent_speaks_first:
          type: boolean
          nullable: true
          description: >-
            Whether the start node had agent_speaks_first=true (bot greeted
            before listening).
        first_step_id:
          type: string
          nullable: true
          description: >-
            Step id the flow began at. Always the start node, but useful for
            sanity checks.
        steps:
          type: array
          description: >-
            Ordered list of node visits. Same step_id may appear multiple times
            if the flow loops back.
          items:
            $ref: '#/components/schemas/FlowTraceStep'
    LeadTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        color:
          type: string
          nullable: true
        sort_order:
          type: integer
        created_at:
          type: string
          format: date-time
    FlowTraceStep:
      type: object
      description: >-
        One node visit during a flow-agent call. Includes routing reason and any
        associated tool I/O or eval decisions.
      required:
        - step_id
        - step_type
        - entered_at
        - eval_decisions
      properties:
        step_id:
          type: string
          description: Node id from flow_config.
        step_type:
          type: string
          enum:
            - start
            - conversation
            - tool_call
            - integration_call
            - transfer
            - end
            - unknown
          description: >-
            Node type. Drives which sibling fields are populated. `unknown` is
            reserved for events emitted by older runtimes that didn't tag
            node_kind.
        step_name:
          type: string
          nullable: true
        entered_at:
          type: string
          format: date-time
        reason:
          type: string
          nullable: true
          description: >
            Why this step was entered. Examples:

            `"start"` — flow began.

            `"eval: <transition_label>"` — the eval LLM picked this transition
            from a conversation node.

            `"tool success"` — fell through after no custom branch matched.

            `"tool custom: <branch_label>"` — a custom JSONPath branch matched.

            `"tool error: <error_message>"` — tool failed.
        tool_call:
          nullable: true
          description: >-
            Present when `step_type` is `tool_call` or `integration_call`.
            Carries the actual args sent and response received, with `kind`
            discriminating the two.
          allOf:
            - $ref: '#/components/schemas/FlowTraceToolCall'
        eval_decisions:
          type: array
          description: >
            Eval-LLM decisions made while at this step. Empty for
            non-conversation nodes; can have multiple

            entries when the user took several turns before transitioning. The
            last entry's `decision` is what fired

            (`"stay"` decisions don't advance; the final non-`"stay"` decision
            moved to the next step).
          items:
            $ref: '#/components/schemas/FlowTraceEvalDecision'
    FlowTraceToolCall:
      type: object
      description: >-
        The actual tool call that fired during a `tool_call` or
        `integration_call` step.
      required:
        - kind
        - tool_name
        - status
      properties:
        kind:
          type: string
          enum:
            - tool_call
            - integration_call
          description: >-
            Discriminator. `tool_call` → webhook/system tool referenced by
            `tool_id`; `integration_call` → typed provider client referenced by
            `provider`+`action`+`integration_id`.
        tool_id:
          type: string
          format: uuid
          nullable: true
          description: Set when `kind=tool_call`. Reference to the tools table row.
        provider:
          type: string
          nullable: true
          description: Set when `kind=integration_call`. e.g. `google_calendar`, `gmail`.
        action:
          type: string
          nullable: true
          description: Set when `kind=integration_call`. e.g. `create_event`, `send_email`.
        integration_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Set when `kind=integration_call`. Connected credential id used for
            this fire.
        tool_name:
          type: string
        status:
          type: string
          enum:
            - success
            - error
          description: >-
            Set by the dispatcher. Hard failures (timeout, redirect or other
            non-2xx status, missing tool) → error. Any 2xx → success, even with
            a soft-fail body.
        args:
          type: object
          nullable: true
          description: >-
            The actual payload sent to the tool / integration. For tool_call
            steps the merge order is standard metadata, then static_parameters,
            then resolved extraction_parameters (later values win collisions);
            for integration_call steps this is the resolved args_template
            (literal / ai_extract values, with all {{node.arg}} and
            {{metadata.key}} tokens interpolated).
        arg_sources:
          type: object
          nullable: true
          additionalProperties:
            type: string
            enum:
              - literal
              - ai_extract
          description: >-
            Per-arg provenance map: which mode each arg came from. `literal`
            includes both plain literals and template-interpolated literals
            (i.e. `{{check.start_time}}`-style cross-node tokens). Null for
            prompt-mode webhook tools.
        response_preview:
          type: string
          nullable: true
          description: >-
            JSON-stringified response body the LLM saw, truncated to ~50KB.
            Truncation is byte-based — long responses may end mid-token.
        raw_response_preview:
          type: string
          nullable: true
          description: >-
            Provider's untouched payload, present only when the LLM-facing
            sanitized view differs from the raw API response. Today this fires
            for Google Calendar `create_event` / `list_events` /
            `check_availability` (the runtime strips ISO timezone offsets and
            reshapes timezone metadata so Live can reliably parse times). Use
            this field for audit; the agent never sees it. Null when the
            provider returned a response that didn't need post-processing.
        error:
          type: string
          nullable: true
        duration_ms:
          type: integer
          nullable: true
    FlowTraceEvalDecision:
      type: object
      description: One eval-LLM decision at a conversation node.
      required:
        - decision
        - decided_at
      properties:
        turn_id:
          type: integer
          nullable: true
          description: >-
            Monotonic counter — same value as the conversation turn the eval was
            running on.
        decision:
          type: string
          description: >
            Either a transition id (taken — flow advances) or `"stay"` (no
            transition; user takes another turn at this node).
        reasoning:
          type: string
          nullable: true
          description: The eval LLM's short justification.
        decided_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````