Get Call Batch

Returns a single batch with its summary data and a paginated list of contacts. Batch data comes from the v_call_batch_summary view; contacts come from the campaign_contacts table.

Endpoint

Property	Value
Function Name	calls-batch-get
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any authenticated agency user

Request

Headers

Authorization: Bearer <supabase_jwt_token>

Query Parameters

Field	Type	Required	Description
batch_id	string (UUID)	Yes	The batch to retrieve
contact_status	string	No	Filter contacts by status: pending, queued, in_progress, completed, failed, skipped
contact_limit	number	No	Number of contacts per page. Default: 50, max: 200.
contact_offset	number	No	Pagination offset for contacts. Default: 0.

Response

Success (200)

{
  "batch": {
    "id": "uuid",
    "agency_id": "uuid",
    "campaign_id": "uuid",
    "campaign_name": "Q1 Outreach",
    "agent_mapping_id": "uuid",
    "agent_name": "Sales Agent",
    "from_number": "+15551234567",
    "status": "processing",
    "total_contacts": 1000,
    "queued": 500,
    "in_progress": 5,
    "completed": 400,
    "failed": 10,
    "skipped": 0,
    "progress_percentage": 41.0,
    "remaining_count": 590,
    "calls_per_minute": 30,
    "max_concurrent": 10,
    "scheduled_for": null,
    "created_at": "2025-01-15T10:30:00Z",
    "started_at": "2025-01-15T10:31:00Z"
  },
  "contacts": [
    {
      "id": "uuid",
      "phone_number": "+15559876543",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "company": "ACME",
      "title": "Manager",
      "status": "completed",
      "call_id": "uuid",
      "attempts": 1,
      "max_attempts": 3,
      "outcome": "answered",
      "duration_seconds": 145,
      "outcome_notes": null,
      "last_attempt_at": "2025-01-15T10:35:00Z",
      "completed_at": "2025-01-15T10:37:25Z",
      "custom_data": {},
      "do_not_call": false,
      "timezone": "EST",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "contact_pagination": {
    "total": 1000,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Error Responses

Status	Condition
400	batch_id query parameter is missing
401	Missing or invalid authorization header
403	User is not associated with an agency
404	Batch not found or does not belong to the user's agency
405	HTTP method is not GET
500	Failed to fetch batch or contacts from the database

Behavior

• Authenticates the user via Supabase JWT and retrieves their agency_id.
• Fetches the batch from v_call_batch_summary filtered by batch_id and agency_id.
• Fetches contacts from campaign_contacts for the batch with optional contact_status filter.
• Returns contacts ordered by created_at ascending with pagination.

Database Tables

Table / View	Operation	Description
users	Read	Fetches user profile to determine agency_id
v_call_batch_summary	Read	Retrieves batch summary with agent and campaign names
campaign_contacts	Read	Retrieves paginated contacts with call details and outcomes

External APIs

None.

Related Functions

• List Call Batches -- View all batches with summary stats
• Create Call Batch -- Create a new batch of outbound calls
• Process Call Batches -- Cron function that initiates calls from queued batches