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

# Get Call Status

> Retrieve the status of an existing call by call_id, or initiate a new outbound call using query parameters.

## Overview

Retrieve the status of an existing call by providing the `call_id`, or initiate a new outbound call using query parameters.

## Parameters

<ParamField body="query" name="call_id" type="string" optional>
  Existing call ID to retrieve status for. If provided, other parameters are ignored.
</ParamField>

<ParamField body="query" name="to_phone_number" type="string" required>
  Phone number to call in E.164 format (e.g., +1234567890). Required if `call_id` is not provided.
</ParamField>

<ParamField body="query" name="agent_id" type="string" required>
  ID of the AI agent to use for the call. Required if `call_id` is not provided.
</ParamField>

<ParamField body="query" name="webhook_url" type="string" optional>
  Optional webhook URL to receive call completion notifications. Must be a valid HTTP/HTTPS URL.
</ParamField>

<ParamField body="query" name="external_call_id" type="string" optional>
  Optional external call ID for tracking purposes.
</ParamField>

## Example Request

<CodeGroup>
  ```bash theme={null}
  curl -X GET "https://api.call24x7.ai/outbound_call?to_phone_number=%2B1234567890&agent_id=agent-123" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Get existing call status theme={null}
  curl -X GET "https://api.call24x7.ai/outbound_call?call_id=12345" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="call_id" type="string">
  Unique identifier for the call
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the call. Possible values: `IDLE`, `RINGING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`
</ResponseField>

<ResponseField name="message" type="string" optional>
  Response message
</ResponseField>

## Example Response

```json theme={null}
{
  "success": true,
  "call_id": "12345",
  "status": "RINGING",
  "message": "Call initiated successfully"
}
```

## Error Responses

<ResponseField name="success" type="boolean">
  Always `false` for errors
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error message
</ResponseField>

<ResponseField name="error_code" type="string">
  Error code. Possible values: `MISSING_PARAMS`, `AGENT_NOT_FOUND`, `CALL_NOT_FOUND`, `INSUFFICIENT_BALANCE`, `INTERNAL_ERROR`
</ResponseField>


## OpenAPI

````yaml GET /outbound_call
openapi: 3.0.1
info:
  title: Call24x7.AI API
  description: >-
    API for making AI-powered phone calls. Initiate outbound calls, handle
    inbound calls, and manage your AI agents programmatically.
  version: 1.0.0
  contact:
    name: Call24x7.AI Support
    email: support@call24x7.ai
    url: https://manage.call24x7.ai
servers:
  - url: https://api.call24x7.ai
    description: Production server
security:
  - bearerAuth: []
paths:
  /outbound_call:
    get:
      tags:
        - Calls
      summary: Get call status or initiate outbound call
      description: >-
        Retrieve the status of an existing call by call_id, or initiate a new
        outbound call using query parameters.
      operationId: getOutboundCall
      parameters:
        - name: call_id
          in: query
          description: Existing call ID to retrieve status for
          required: false
          schema:
            type: string
        - name: to_phone_number
          in: query
          description: >-
            Phone number to call (E.164 format, e.g., +1234567890). Required if
            call_id is not provided.
          required: false
          schema:
            type: string
            pattern: ^\+[1-9]\d{1,14}$
        - name: agent_id
          in: query
          description: >-
            ID of the AI agent to use for the call. Required if call_id is not
            provided.
          required: false
          schema:
            type: string
        - name: webhook_url
          in: query
          description: Optional webhook URL to receive call completion notifications
          required: false
          schema:
            type: string
            format: uri
        - name: external_call_id
          in: query
          description: Optional external call ID for tracking
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Call initiated successfully or call status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Call or agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CallResponse:
      type: object
      required:
        - success
        - call_id
        - status
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        call_id:
          type: string
          description: Unique identifier for the call
        status:
          type: string
          description: Current status of the call
          enum:
            - IDLE
            - RINGING
            - IN_PROGRESS
            - COMPLETED
            - FAILED
        message:
          type: string
          description: Response message
    Error:
      type: object
      required:
        - success
        - message
        - error_code
      properties:
        success:
          type: boolean
          description: Always false for errors
          example: false
        message:
          type: string
          description: Human-readable error message
        error_code:
          type: string
          description: Machine-readable error code
          enum:
            - MISSING_PARAMS
            - UNAUTHORIZED
            - INSUFFICIENT_BALANCE
            - AGENT_NOT_FOUND
            - CALL_NOT_FOUND
            - INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Include your API key in the Authorization header
        as: Bearer YOUR_API_KEY

````