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

# Get A Batch Call By Id

> Get detailed information about a batch call including all recipients.



## OpenAPI

````yaml https://api.threetone.in/openapi.json get /v1/voiceai/batch-calling/{batch_id}
openapi: 3.1.0
info:
  title: Threetone API Documentation
  version: 1.0.0
servers:
  - url: https://api.threetone.in
    description: Production
security: []
paths:
  /v1/voiceai/batch-calling/{batch_id}:
    get:
      tags:
        - Batch Calling
      summary: Get A Batch Call By Id
      description: Get detailed information about a batch call including all recipients.
      operationId: get_batch_call
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCallDetailedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    BatchCallDetailedResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique batch call ID
        phone_number_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number Id
          description: Caller phone number ID
        phone_provider:
          anyOf:
            - $ref: '#/components/schemas/TelephonyProvider'
            - type: 'null'
        whatsapp_params:
          anyOf:
            - $ref: '#/components/schemas/BatchCallWhatsAppParams'
            - type: 'null'
        name:
          type: string
          title: Name
          description: Name of the batch call job
        agent_id:
          type: string
          title: Agent Id
          description: Agent ID to use for calls
        created_at_unix:
          type: integer
          title: Created At Unix
          description: Unix timestamp when created
        scheduled_time_unix:
          type: integer
          title: Scheduled Time Unix
          description: Unix timestamp when scheduled to start
        total_calls_dispatched:
          type: integer
          title: Total Calls Dispatched
          description: Number of calls dispatched
          default: 0
        total_calls_scheduled:
          type: integer
          title: Total Calls Scheduled
          description: Number of calls scheduled
          default: 0
        total_calls_finished:
          type: integer
          title: Total Calls Finished
          description: Number of calls finished (completed + failed)
          default: 0
        last_updated_at_unix:
          type: integer
          title: Last Updated At Unix
          description: Unix timestamp of last update
        status:
          $ref: '#/components/schemas/BatchCallStatus'
          description: Current status of the batch job
        retry_count:
          type: integer
          title: Retry Count
          description: Number of retries attempted
          default: 0
        agent_name:
          type: string
          title: Agent Name
          description: Name of the agent
        recipients:
          items:
            $ref: '#/components/schemas/OutboundCallRecipientResponse'
          type: array
          title: Recipients
          description: All recipients in this batch
      type: object
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - last_updated_at_unix
        - status
        - agent_name
        - recipients
      title: BatchCallDetailedResponse
      description: Detailed response model for a batch call including all recipients.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TelephonyProvider:
      type: string
      enum:
        - twilio
        - vobiz
        - sip_trunk
      title: TelephonyProvider
      description: Telephony provider for batch calls.
    BatchCallWhatsAppParams:
      properties:
        whatsapp_phone_number_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Whatsapp Phone Number Id
        whatsapp_call_permission_request_template_name:
          type: string
          title: Whatsapp Call Permission Request Template Name
        whatsapp_call_permission_request_template_language_code:
          type: string
          title: Whatsapp Call Permission Request Template Language Code
      type: object
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
      title: BatchCallWhatsAppParams
      description: WhatsApp parameters for batch calls (future support).
    BatchCallStatus:
      type: string
      enum:
        - pending
        - in_progress
        - completed
        - failed
        - cancelled
      title: BatchCallStatus
      description: Status of a batch call job.
    OutboundCallRecipientResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique recipient ID
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
          description: E164 phone number to call
        whatsapp_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Whatsapp User Id
          description: WhatsApp user ID (future)
        status:
          $ref: '#/components/schemas/BatchCallRecipientStatus'
          description: Current status of this recipient
        created_at_unix:
          type: integer
          title: Created At Unix
          description: Unix timestamp when created
        updated_at_unix:
          type: integer
          title: Updated At Unix
          description: Unix timestamp of last update
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Linked conversation ID once call starts
        conversation_initiation_client_data:
          anyOf:
            - $ref: '#/components/schemas/ConversationInitiationClientData-Output'
            - type: 'null'
      type: object
      required:
        - id
        - status
        - created_at_unix
        - updated_at_unix
      title: OutboundCallRecipientResponse
      description: Response model for a batch call recipient.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    BatchCallRecipientStatus:
      type: string
      enum:
        - pending
        - dispatched
        - initiated
        - in_progress
        - completed
        - failed
        - cancelled
        - voicemail
      title: BatchCallRecipientStatus
      description: Status of a batch call recipient.
    ConversationInitiationClientData-Output:
      properties:
        conversation_config_override:
          anyOf:
            - $ref: '#/components/schemas/ConversationConfigClientOverride-Output'
            - type: 'null'
        custom_llm_extra_body:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Llm Extra Body
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: End user ID for tracking
        source_info:
          anyOf:
            - $ref: >-
                #/components/schemas/app__domains__batch_calling__schemas__ConversationInitiationSourceInfo-Output
            - type: 'null'
        dynamic_variables:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - type: integer
                  - type: number
                  - type: boolean
                  - type: 'null'
              type: object
            - type: 'null'
          title: Dynamic Variables
      type: object
      title: ConversationInitiationClientData
      description: Client data for conversation initiation (per-recipient customization).
    ConversationConfigClientOverride-Output:
      properties:
        turn:
          anyOf:
            - $ref: '#/components/schemas/TurnConfigOverride'
            - type: 'null'
          description: Configuration for turn detection
        tts:
          anyOf:
            - $ref: '#/components/schemas/TTSConversationalConfigOverride'
            - type: 'null'
          description: Configuration for conversational text to speech
        conversation:
          anyOf:
            - $ref: '#/components/schemas/ConversationConfigOverride'
            - type: 'null'
          description: Configuration for conversational events
        agent:
          anyOf:
            - $ref: '#/components/schemas/AgentConfigOverrideInput-Output'
            - type: 'null'
          description: Agent specific configuration
      type: object
      title: ConversationConfigClientOverride-Input
      description: >-
        Subset of conversation settings the client may override at conversation
        start.
    app__domains__batch_calling__schemas__ConversationInitiationSourceInfo-Output:
      properties:
        source:
          anyOf:
            - $ref: >-
                #/components/schemas/app__domains__batch_calling__schemas__ConversationInitiationSource
            - type: 'null'
        version:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Version
          description: SDK version number
      type: object
      title: ConversationInitiationSourceInfo
      description: Information about conversation initiation source.
    TurnConfigOverride:
      properties:
        soft_timeout_config:
          anyOf:
            - $ref: '#/components/schemas/SoftTimeoutConfigOverride'
            - type: 'null'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
      type: object
      title: TurnConfigOverride
    TTSConversationalConfigOverride:
      properties:
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
          description: The voice ID to use for TTS
        stability:
          anyOf:
            - type: number
            - type: 'null'
          title: Stability
          description: The stability of generated speech
        speed:
          anyOf:
            - type: number
            - type: 'null'
          title: Speed
          description: The speed of generated speech
        similarity_boost:
          anyOf:
            - type: number
            - type: 'null'
          title: Similarity Boost
          description: The similarity boost for generated speech
      type: object
      title: TTSConversationalConfigOverride
    ConversationConfigOverride:
      properties:
        text_only:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Text Only
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
      type: object
      title: ConversationConfigOverride
    AgentConfigOverrideInput-Output:
      properties:
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: >-
            Primary ISO 639-1 language code for voice (e.g. en, hi, kn). Short
            codes only, not regional BCP-47 (e.g. not hi-IN).
        max_conversation_duration_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Max Conversation Duration Message
          description: >-
            If non-empty, the message the agent will send when max conversation
            duration is reached.
        prompt:
          anyOf:
            - $ref: '#/components/schemas/PromptAgentAPIModelOverride-Output'
            - type: 'null'
          description: The prompt for the agent
      type: object
      title: AgentConfigOverride-Input
    app__domains__batch_calling__schemas__ConversationInitiationSource:
      type: string
      enum:
        - unknown
        - android_sdk
        - node_js_sdk
        - react_native_sdk
        - react_sdk
        - js_sdk
        - python_sdk
        - widget
        - sip_trunk
        - twilio
        - vobiz
        - genesys
        - swift_sdk
        - whatsapp
        - flutter_sdk
        - batch_call
      title: ConversationInitiationSource
      description: Source of conversation initiation.
    SoftTimeoutConfigOverride:
      properties:
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
      type: object
      title: SoftTimeoutConfigOverride
    PromptAgentAPIModelOverride-Output:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: The prompt for the agent
        llm:
          anyOf:
            - $ref: '#/components/schemas/LLM'
            - type: 'null'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        tool_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool Ids
          description: A list of IDs of tools used by the agent
        native_mcp_server_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Native Mcp Server Ids
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeBaseLocator'
              type: array
            - type: 'null'
          title: Knowledge Base
          description: A list of knowledge bases to be used by the agent
      type: object
      title: PromptAgentAPIModelOverride-Input
    LLM:
      type: string
      enum:
        - gpt-5-mini
        - gemini-2.5-flash
        - gemini-3-flash-preview
        - gpt-4o-mini
      title: LLM
    KnowledgeBaseLocator:
      properties:
        type:
          $ref: '#/components/schemas/KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          title: Name
          description: The name of the knowledge base
        id:
          type: string
          title: Id
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
          default: auto
      type: object
      required:
        - type
        - name
        - id
      title: KnowledgeBaseLocator
      description: >-
        Reference to a knowledge base document (locator for agent attachment).

        Used when attaching knowledge bases to an agent. Canonical definition
        lives here;

        do not duplicate in other domains.
      example:
        id: '123'
        name: My Knowledge Base
        type: file
        usage_mode: auto
    KnowledgeBaseDocumentType:
      type: string
      enum:
        - file
        - url
        - text
        - folder
      title: KnowledgeBaseDocumentType
      description: Type of knowledge base document
    DocumentUsageModeEnum:
      type: string
      enum:
        - prompt
        - auto
      title: DocumentUsageModeEnum
      description: |-
        How the document is used in agent context.
        - prompt: Always include full document in LLM context
        - auto: Use RAG to retrieve relevant chunks
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API key for programmatic access
      in: header
      name: x-api-key
    HTTPBearer:
      type: http
      description: JWT Bearer token for dashboard access
      scheme: bearer

````