AI Voice Agent Sessions

An AI session represents one AI conversation on a call. Sessions are created for inbound DID routes to an AI agent and for outbound AI calls. Use sessions to show call outcomes, conversation turns, billing status, and failure reasons in your application.

List Sessions

Endpoint	Method	Auth
/v1/ai/sessions	GET	Required

Query parameters:

Parameter	Type	Description
limit	integer	Defaults to 100. Values less than 1 or greater than 200 are reset to 100.
status	string	Optional exact status filter.
agent_id	string	Optional agent filter. ai_agent_id is also accepted.

curl -sS 'https://api.minivoice.eu/v1/ai/sessions?agent_id=agent_20260707T120000.000000000&limit=25' \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "count": 1,
  "data": [
    {
      "id": "agent_session_123",
      "call_id": "call_123",
      "agent_id": "agent_20260707T120000.000000000",
      "ai_agent_id": "agent_20260707T120000.000000000",
      "agent_name": "Receptionist",
      "status": "completed",
      "started_at": "2026-07-07T12:05:10Z",
      "ended_at": "2026-07-07T12:07:30Z",
      "completed_at": "2026-07-07T12:07:30Z",
      "created_at": "2026-07-07T12:05:00Z",
      "direction": "outbound",
      "current_turn": 4,
      "turn_count": 4,
      "model": "gpt-4.1-mini",
      "voice": "alloy",
      "runtime_type": "turn_based",
      "billed_minutes": 3,
      "final_customer_charge": "0.030000",
      "billing_status": "settled",
      "campaign_outcome": "confirmed",
      "campaign_confirmed": true,
      "callback_requested": false,
      "human_requested": false,
      "completion_reason": "hangup"
    }
  ]
}

Get One Session

Endpoint	Method	Auth
/v1/ai/sessions/:id	GET	Required

curl -sS https://api.minivoice.eu/v1/ai/sessions/agent_session_123 \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "data": {
    "id": "agent_session_123",
    "call_id": "call_123",
    "agent_id": "agent_20260707T120000.000000000",
    "status": "completed",
    "direction": "outbound",
    "turn_count": 2,
    "billing_status": "settled",
    "turns": [
      {
        "id": "turn_1",
        "turn_number": 1,
        "caller_transcript": "I can make the appointment.",
        "assistant_text": "Great, I have marked your appointment as confirmed.",
        "latency_ms": 1800,
        "status": "completed",
        "model": "gpt-4.1-mini",
        "voice": "alloy",
        "created_at": "2026-07-07T12:05:30Z"
      }
    ]
  }
}

Important Fields

Field	Description
status	Session lifecycle state. Completed and failed sessions are final.
completion_reason	Reason recorded when the session ends, such as hangup or transferred.
transfer_target	Present when the call was transferred.
failure_reason	Sanitized failure text when a session or turn failed.
billed_minutes	Customer-facing billable minutes.
final_customer_charge	Customer-facing final charge as a string.
billing_status	Billing settlement state exposed to the customer.

Provider cost fields, pricing plan IDs, and raw provider call IDs are not exposed by the public session API.

Common Failure

{
  "error": {
    "code": "ai_agent_session_not_found",
    "message": "AI agent session not found"
  }
}

Testing

Place one inbound AI-agent call and one outbound AI call. After each call ends, list sessions filtered by agent_id, fetch the session detail, and verify that turns are ordered by turn number. In your UI, display session-level failure separately from turn-level failure because a session may complete after a failed turn.