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

# Get Batch Details

> Inspect batch metadata and page through associated calls with filtering and sorting.

## Overview

Fetch detailed information for a single batch, including campaign metadata, status, and a paginated list of call records. This endpoint supports advanced filtering, sorting, and searching to help you analyze call data. Use it for monitoring execution from the dashboard or building custom analytics.

## Prerequisites

* Bearer token for an authenticated user who owns the batch.
* The batch `id` you obtained during creation.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token for the authenticated user.
</ParamField>

<ParamField path="id" type="string" required>
  Batch identifier you want to inspect.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for paginated calls.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Maximum call records to return per page (default: 10).
</ParamField>

<ParamField query="filter" type="string">
  JSON stringified filter object to filter calls by specific fields. Example: `{"callStatus":"completed"}`.
</ParamField>

<ParamField query="sortBy" type="string">
  Field to sort by (e.g., "createdAt").
</ParamField>

<ParamField query="sortOrder" type="string" allowedValues="asc,desc" default="asc">
  Sort order: "asc" for ascending or "desc" for descending.
</ParamField>

<ParamField query="search" type="string">
  Search term to filter calls across dynamic fields (e.g., customer name, phone number).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location '{{baseUrl}}/api/call/batch-details/67def9053495307c718d9dfb?page=1&limit=10&sortBy=createdAt&sortOrder=desc' \
    --header 'Authorization: Bearer {{authToken}}'
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Calls fetched successfully",
    "status": true,
    "code": 200,
    "errorMessage": "",
    "data": {
      "batchId": "67def9053495307c718d9dfb",
      "batchName": "Marketing Campaign May 2025",
      "batchStatus": "active",
      "page": 1,
      "limit": 10,
      "total": 150,
      "totalPages": 15,
      "data": [
        {
          "_id": "64e5f12345abcdef11111111",
          "phoneNumber": "12125551234",
          "name": "Emily Davis",
          "account_id": "ACC-5678",
          "priority": "high",
          "phoneLogs": [
            {
              "callStatus": "completed",
              "callDuration": 120,
              "recordingUrl": "https://example.com/recording.mp3",
              "transcript": "Call transcript here...",
              "createdAt": "2025-05-15T14:30:00.000Z"
            }
          ],
          "createdAt": "2025-05-15T14:00:00.000Z"
        }
      ]
    }
  }
  ```
</ResponseExample>

<ResponseField name="data" type="object" required>
  Contains batch metadata and paginated call records.
</ResponseField>

<ResponseField name="data.batchId" type="string" required>
  The batch identifier.
</ResponseField>

<ResponseField name="data.batchName" type="string" required>
  The name of the batch.
</ResponseField>

<ResponseField name="data.batchStatus" type="string" required>
  Current status of the batch (e.g., "active", "completed", "paused").
</ResponseField>

<ResponseField name="data.page" type="integer" required>
  Current page number.
</ResponseField>

<ResponseField name="data.limit" type="integer" required>
  Number of records per page.
</ResponseField>

<ResponseField name="data.total" type="integer" required>
  Total number of calls in the batch matching the filter criteria.
</ResponseField>

<ResponseField name="data.totalPages" type="integer" required>
  Total number of pages available.
</ResponseField>

<ResponseField name="data.data" type="array[object]" required>
  Array of call records with enriched data including phone logs, recording URLs, and transcripts when available.
</ResponseField>

## Error Handling

* **400 Bad Request** – Invalid batch ID format, invalid filter JSON, or query parameters out of range.
* **404 Not Found** – Batch not found or does not belong to the authenticated user.
* **500 Internal Server Error** – Failed to aggregate batch data; retry or contact support.

<Note>
  **Advanced Features:**

  * **Filtering:** Use the `filter` parameter with JSON to filter calls by specific fields from the phone logs
  * **Sorting:** Sort by any field using `sortBy` and control order with `sortOrder`
  * **Searching:** The `search` parameter performs a regex search across all dynamic string fields in call records
  * Phone logs are automatically included with each call record when available
</Note>

<Tip>
  For real-time monitoring, combine this endpoint with webhooks to track batch progress. Use filtering and sorting to identify specific call outcomes or issues.
</Tip>


## OpenAPI

````yaml GET /api/call/batch-details/{id}
openapi: 3.1.0
info:
  title: Weya AI Public API
  description: >-
    Public API documentation for Weya AI platform - Call Management and DNC (Do
    Not Call) APIs
  version: 1.0.0
servers:
  - url: >-
      https://nexusdev-wjs-api-dev.mangoforest-291de162.swedencentral.azurecontainerapps.io
    description: Development server
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /api/call/batch-details/{id}:
    get:
      tags:
        - Call Management
      summary: Get batch details by ID
      description: >-
        Inspect batch metadata and page through associated calls with filtering
        and sorting
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: filter
          schema:
            type: string
        - in: query
          name: sortBy
          schema:
            type: string
        - in: query
          name: sortOrder
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - in: query
          name: search
          schema:
            type: string
      responses:
        '200':
          description: Batch details fetched successfully
        '400':
          description: Invalid batchId
        '404':
          description: Batch not found
        '500':
          description: Internal Server Error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication for workspace access
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key used for programmatic calling integrations. Find it under
        Settings → API access in your workspace.

````