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

# Search outbound calls

> Search outbound calls by destination.


Look up calls by the real (unmasked) destination number/SIP URI, without ever putting it in a URL. The destination is matched against a server-side blind index — the raw value in your request is never logged or echoed back; results still return the destination masked, like every other endpoint.

The `destination` is optional — omit it to combine the other filters (phase, outcome, clientReferenceId, channelConnectionId, time window) as a general filtered search.


## OpenAPI

````yaml agent-platform/api-specs/outbound-calls.yaml post /api/v1/project/{projectSlug}/{env}/outbound-calls/search
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/search:
    post:
      tags:
        - Outbound Calls
      summary: Search outbound calls by destination
      description: |
        Search outbound calls by destination.
      operationId: searchOutboundCalls
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - $ref: '#/components/parameters/Env'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchOutboundCallsRequest'
            example:
              destination:
                type: phone
                number: '+14155550123'
      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
  schemas:
    SearchOutboundCallsRequest:
      type: object
      additionalProperties: false
      properties:
        destination:
          $ref: '#/components/schemas/OutboundCallDestination'
        channelConnectionId:
          type: string
          minLength: 1
        phase:
          $ref: '#/components/schemas/OutboundCallPhase'
        outcome:
          $ref: '#/components/schemas/OutboundCallOutcome'
        clientReferenceId:
          type: string
          minLength: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        limit:
          type: integer
          minimum: 1
          maximum: 100
        cursor:
          type: string
          minLength: 1
    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.
    OutboundCallDestination:
      description: Destination for the call — a phone number or a SIP URI.
      oneOf:
        - type: object
          required:
            - type
            - number
          properties:
            type:
              type: string
              enum:
                - phone
            number:
              type: string
              minLength: 1
              description: E.164 phone number.
        - type: object
          required:
            - type
            - sipUri
          properties:
            type:
              type: string
              enum:
                - sip
            sipUri:
              type: string
              minLength: 1
    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
    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).

````