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

# List outbound calls

> List outbound calls.


Paginated list of outbound calls for the project/environment, most recent first. Destinations are always masked. Combine filters freely; all supplied filters apply together (AND).


## OpenAPI

````yaml agent-platform/api-specs/outbound-calls.yaml get /api/v1/project/{projectSlug}/{env}/outbound-calls
openapi: 3.1.0
info:
  title: Outbound Dial API
  version: 1.0.0
  summary: >-
    Project-scoped API for placing, tracking, and terminating outbound phone/SIP
    calls through KoreVG.
  description: >
    Places an outbound call through a project's telephony channel connection,
    and lets you

    track it through to completion — either by polling, by listing/searching the
    call log, or

    by subscribing to a live server-sent-events stream.


    Outbound calls are asynchronous by nature. Initiating a call returns
    immediately with an

    `outboundCallId` and an initial `phase` of `accepted` — the call has been
    accepted for

    submission, not yet answered. Track its progress with `GET
    .../outbound-calls/{id}`, the

    live event stream at `GET .../outbound-calls/{id}/events`, or by
    listing/searching the call

    log.


    ### Call lifecycle


    A call moves through `phase` values in order: `accepted` → `dialing` →
    `ringing` →

    `in_progress` (answered) → `terminal` (call has ended, either way). Once a
    call reaches

    `terminal`, `outcome` explains how it ended (`completed`, `busy`,
    `rejected`, `no_answer`,

    `machine`, `failed`, `canceled`, or `expired`), and `failureReason` carries
    additional

    detail for a non-`completed` outcome. A call that connects (`in_progress`)
    creates a

    session — `sessionId` on the call record correlates to that session's own
    history/traces

    once available.


    ### Idempotency


    Every initiate request requires an `idempotencyKey`. Retrying the identical
    request body

    with the same key returns the **original** call (`200`) instead of placing a
    duplicate

    call (`201` on first submission). Reusing the same key with a **different**
    body is

    rejected with `409 IDEMPOTENCY_CONFLICT` — pick a new key for a genuinely
    different call.


    ### Authentication


    Authenticate with the `x-api-key` header, using a Platform API key

    (`abl_...`) scoped to the project you are calling. Write operations
    (initiate, terminate)

    require the `outbound_calls.initiate` scope; read operations (lookup, list,
    summary,

    search, event stream) require `outbound_calls.read`.


    ### Privacy


    `destination` is always returned masked on the wire (e.g. `+1*******67`) —
    the full

    number is never echoed back after initiation. `providerCallSid` (the
    underlying telephony

    provider's own call identifier) is likewise masked in call-log responses.
    List and search

    responses never carry an unmasked destination either; use `POST
    .../outbound-calls/search`

    with the real number to look a call up by destination — it is matched
    against a blind

    index server-side, so the raw number never appears in a URL or is logged in
    access logs.


    ### Isolation


    A call belonging to a different project is concealed as `404
    CHANNEL_NOT_FOUND` /

    `404 Not Found`, never `403` — the API does not disclose whether a resource
    exists outside

    your project's scope.
servers:
  - url: https://example.com
    description: Base URL of your platform.
    variables:
      host:
        default: runtime.example.com
security:
  - ApiKeyAuth: []
tags:
  - name: Outbound Calls
    description: Place and track outbound phone/SIP calls.
paths:
  /api/v1/project/{projectSlug}/{env}/outbound-calls:
    get:
      tags:
        - Outbound Calls
      summary: List outbound calls
      description: |
        List outbound calls.
      operationId: listOutboundCalls
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - $ref: '#/components/parameters/Env'
        - name: channelConnectionId
          in: query
          description: Filter to calls placed through one channel connection.
          schema:
            type: string
            minLength: 1
        - name: phase
          in: query
          description: Filter by current lifecycle phase.
          schema:
            $ref: '#/components/schemas/OutboundCallPhase'
        - name: outcome
          in: query
          description: >-
            Filter by terminal outcome. Only calls that have reached
            `phase=terminal` have one.
          schema:
            $ref: '#/components/schemas/OutboundCallOutcome'
        - name: clientReferenceId
          in: query
          description: Filter to calls initiated with this caller-supplied reference.
          schema:
            type: string
            minLength: 1
        - name: from
          in: query
          description: Inclusive ISO 8601 lower bound on call creation time.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Exclusive ISO 8601 upper bound on call creation time.
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Page of matching calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundCallListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ProjectSlug:
      name: projectSlug
      in: path
      required: true
      description: The project's slug.
      schema:
        type: string
        minLength: 1
    Env:
      name: env
      in: path
      required: true
      description: >-
        Deployment environment segment the call runs under, e.g. `production`,
        `staging`, `dev`.
      schema:
        type: string
        minLength: 1
    Limit:
      name: limit
      in: query
      description: Page size.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      description: Pass the previous response's `nextCursor` to get the next page.
      schema:
        type: string
        minLength: 1
  schemas:
    OutboundCallPhase:
      type: string
      description: >
        Lifecycle phase, in order: accepted=submitted, not yet dialing;
        dialing=submitted to

        the carrier; ringing=destination is ringing; in_progress=answered, call
        is live;

        terminal=call has ended (see `outcome`).
      enum:
        - accepted
        - dialing
        - ringing
        - in_progress
        - terminal
    OutboundCallOutcome:
      type: string
      description: >
        How a terminal call ended. completed=ended normally after connecting;

        busy=destination was busy; rejected=destination actively
        declined/rejected the call;

        no_answer=rang without being picked up; machine=answering machine
        detected (only

        possible with `amdMode` other than `off`); failed=a hard failure
        prevented completion;

        canceled=terminated by a `.../terminate` call before it connected;
        expired=the call was

        abandoned before reaching a provider-reported outcome.
      enum:
        - completed
        - busy
        - rejected
        - no_answer
        - machine
        - failed
        - canceled
        - expired
    OutboundCallListResponse:
      type: object
      required:
        - success
        - data
        - nextCursor
      properties:
        success:
          type: boolean
          const: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/OutboundCallResource'
        nextCursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as `cursor` to fetch the next page. Null when there are no more
            results.
    OutboundCallResource:
      type: object
      required:
        - outboundCallId
        - channelConnectionId
        - environment
        - destinationType
        - destination
        - initiationState
        - phase
        - outcome
        - failureReason
        - amdMode
        - providerCallSid
        - sessionId
        - statusHistory
        - createdAt
        - updatedAt
      properties:
        outboundCallId:
          type: string
        channelConnectionId:
          type: string
        environment:
          type: string
          description: Deployment environment segment the call was placed under.
        destinationType:
          type: string
          enum:
            - phone
            - sip
        destination:
          type: string
          description: >-
            Always masked (e.g. `+1*******23`). The unmasked value is never
            returned after initiation — use `.../search` to look up by real
            number.
        clientReferenceId:
          type:
            - string
            - 'null'
        initiationState:
          $ref: '#/components/schemas/OutboundInitiationState'
        phase:
          $ref: '#/components/schemas/OutboundCallPhase'
        outcome:
          oneOf:
            - $ref: '#/components/schemas/OutboundCallOutcome'
            - type: 'null'
        failureReason:
          type:
            - string
            - 'null'
          description: Additional detail for a non-`completed` terminal outcome.
        amdMode:
          $ref: '#/components/schemas/OutboundAmdMode'
        providerCallSid:
          type:
            - string
            - 'null'
          description: The telephony provider's own call identifier, masked.
        sessionId:
          type:
            - string
            - 'null'
          description: >-
            Set once the call connects (`phase=in_progress`) — correlates to the
            session created for the conversation.
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/OutboundCallStatusHistoryEntry'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable detail.
            requestId:
              type: string
              description: Correlates this failure to platform-side logs.
    OutboundInitiationState:
      type: string
      description: >
        Submit-lifecycle state, distinct from `phase` — tracks getting the
        request to the

        telephony provider, not the call itself. created=call row written, not
        yet submitted;

        provider_requesting=submit in flight; submitted=provider accepted the
        request;

        provider_request_unknown=the submit outcome could not be confirmed (will
        be

        reconciled); failed_to_submit=submission failed before reaching the
        provider.
      enum:
        - created
        - provider_requesting
        - submitted
        - provider_request_unknown
        - failed_to_submit
    OutboundAmdMode:
      type: string
      description: >
        Answering-machine detection behavior. off=disabled, no AMD processing;
        continue=detect

        and report via `amdResult`, but let the call proceed regardless;
        disconnect=detect and

        automatically hang up on a machine.
      enum:
        - 'off'
        - continue
        - disconnect
    OutboundCallStatusHistoryEntry:
      type: object
      required:
        - phase
        - outcome
        - providerEventAt
        - ingestedAt
      properties:
        phase:
          $ref: '#/components/schemas/OutboundCallPhase'
        outcome:
          oneOf:
            - $ref: '#/components/schemas/OutboundCallOutcome'
            - type: 'null'
        providerEventAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the telephony provider says the transition happened. Null when
            the provider did not supply a timestamp.
        ingestedAt:
          type: string
          format: date-time
          description: When the platform recorded this transition.
  responses:
    Unauthorized:
      description: Missing or invalid `x-api-key`, or the key lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Unexpected failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Project-bound Platform API key (`abl_...`). The key must carry
        `outbound_calls.initiate`

        for write operations (initiate, terminate) or `outbound_calls.read` for
        read operations

        (lookup, list, summary, search, event stream).

````