Calls

List Calls

/api/v1/calls

GET

Retrieve recent call records sorted by ranking

Endpoint

GET /api/v1/calls

Description

Returns a list of recent calls (up to 100 most recent) sorted by risk ranking. This provides a historical view of all processed calls with complete analysis data.

Request

No parameters required.

cURL Example

curl http://localhost:8000/api/v1/calls

Response

Returns an array of call records.

call_id

string

required

Unique call identifier

call_control_id

string

required

Telnyx call control ID

from_masked

string

required

Masked caller phone number (e.g., "•••1234")

string

required

Emergency number that was called

duration_seconds

number

Call duration in seconds

audio

object

required

Audio analysis data

audio.sample_rate

number

required

Audio sample rate (typically 8000 Hz)

audio.voiced_seconds

number

required

Seconds of detected voice activity

audio.distress_score

number

required

Average distress score from audio analysis (0.0 to 1.0)

audio.distress_max

number

required

Maximum distress score during call

audio.distress_bucket

string

required

Categorical distress level: CALM, ELEVATED, or HIGH_RISK

nlp

object

required

Natural language processing results

nlp.transcript

string

Full call transcript

nlp.emotion

object

Emotional analysis

nlp.emotion.label

string

Emotion label (e.g., "DISTRESSED", "CALM", "WORRIED")

nlp.emotion.intensity

number

Emotion intensity (0.0 to 1.0)

nlp.emotion.sentiment

string

Sentiment: positive, neutral, or negative

nlp.category

string

Service category: EMS, FIRE, POLICE, or OTHER

nlp.category_confidence

number

Confidence score for category classification

nlp.tags

array

Array of semantic tags extracted from transcript

nlp.summary

string

AI-generated summary of the call

risk

object

required

Risk assessment

risk.level

string

required

Risk level: CRITICAL, ELEVATED, NORMAL, or LOW

risk.score

number

required

Numeric risk score (0.0 to 1.0)

routing

object

required

Routing recommendations

routing.priority

string

required

Priority level (same as risk.level)

routing.recommended_unit

string

required

Recommended emergency service unit

routing.recommended_tags

array

required

Tags for routing decisions

ranking

object

required

Ranking information for queue sorting

ranking.weight

number

required

Combined weight for sorting

ranking.score

number

required

Ranking score

ranking.created_at

string

required

ISO 8601 timestamp when call ended

Success Response (200 OK)

[
  {
    "call_id": "abc123-def456-ghi789",
    "call_control_id": "v3:xyz789-abc123",
    "from_masked": "•••1234",
    "to": "+15555559911",
    "duration_seconds": 135,
    "audio": {
      "sample_rate": 8000,
      "voiced_seconds": 87.3,
      "distress_score": 0.72,
      "distress_max": 0.89,
      "distress_bucket": "HIGH_RISK"
    },
    "nlp": {
      "transcript": "Help! There's a fire in the kitchen. Smoke is everywhere!",
      "emotion": {
        "label": "DISTRESSED",
        "intensity": 0.85,
        "sentiment": "negative"
      },
      "category": "FIRE",
      "category_confidence": 0.95,
      "tags": ["FIRE", "SMOKE"],
      "summary": "Caller reports active fire in kitchen with heavy smoke"
    },
    "risk": {
      "level": "CRITICAL",
      "score": 0.89
    },
    "routing": {
      "priority": "CRITICAL",
      "recommended_unit": "FIRE",
      "recommended_tags": ["FIRE", "SMOKE"]
    },
    "ranking": {
      "weight": 103,
      "score": 0.89,
      "created_at": "2026-03-03T23:17:45Z"
    }
  }
]

Sorting Logic

Calls are sorted by:

Ranking weight (descending)
Risk score (descending)
Creation timestamp (descending - newest first)

This prioritizes:

Highest-risk calls first
Most recent calls within same risk level

Implementation

Location: app/main.py:707-730

Usage Notes

Returns up to 100 most recent calls (limit set by InMemoryCallStore)
In dev mode, uses in-memory storage (lost on restart)
In production, would use persistent database
Response includes Cache-Control: no-store header

Get Call Details

/api/v1/calls/{call_id}

GET

Retrieve complete details for a specific call

Endpoint

GET /api/v1/calls/{call_id}

Path Parameters

call_id

string

required

The call session ID to retrieve

Request

cURL Example

curl http://localhost:8000/api/v1/calls/abc123-def456-ghi789

Response

string

required

Call ID

status

string

required

Current queue status (from queue item if exists)

caller

object

required

Caller information

caller.from_masked

string

required

Masked phone number

caller.to

string

required

Called number

timing

object

required

Call timing information

timing.duration_seconds

number

Call duration in seconds

timing.created_at

string

required

ISO 8601 timestamp when call ended

audio

object

required

Audio analysis (same structure as in list response)

risk

object

required

Risk assessment (same structure as in list response)

nlp

object

required

NLP results (same structure as in list response)

routing

object

required

Routing recommendations (same structure as in list response)

Success Response (200 OK)

{
  "id": "abc123-def456-ghi789",
  "status": "IN_PROGRESS",
  "caller": {
    "from_masked": "•••1234",
    "to": "+15555559911"
  },
  "timing": {
    "duration_seconds": 135,
    "created_at": "2026-03-03T23:17:45Z"
  },
  "audio": {
    "sample_rate": 8000,
    "voiced_seconds": 87.3,
    "distress_score": 0.72,
    "distress_max": 0.89,
    "distress_bucket": "HIGH_RISK"
  },
  "risk": {
    "level": "CRITICAL",
    "score": 0.89
  },
  "nlp": {
    "transcript": "Help! There's a fire in the kitchen. Smoke is everywhere!",
    "emotion": {
      "label": "DISTRESSED",
      "intensity": 0.85,
      "sentiment": "negative"
    },
    "category": "FIRE",
    "category_confidence": 0.95,
    "tags": ["FIRE", "SMOKE"],
    "summary": "Caller reports active fire in kitchen with heavy smoke"
  },
  "routing": {
    "priority": "CRITICAL",
    "recommended_unit": "FIRE",
    "recommended_tags": ["FIRE", "SMOKE"]
  }
}

Error Response (404 Not Found)

{
  "detail": "Call not found"
}

Implementation

Location: app/main.py:814-844

Usage Notes

Searches through recent calls in memory
Merges call record data with queue status
Used by UI to display detailed call view
Returns 404 if call ID not found in recent calls

Endpoints

Schemas

List Calls

Endpoint

Description

Request

cURL Example

Response

Success Response (200 OK)

Sorting Logic

Implementation

Usage Notes

Get Call Details

Endpoint

Path Parameters

Request

cURL Example

Response

Success Response (200 OK)

Error Response (404 Not Found)

Implementation

Usage Notes

Build docs developers (and LLMs) love

Endpoints

Schemas

​List Calls

​Endpoint

​Description

​Request

​cURL Example

​Response

​Success Response (200 OK)

​Sorting Logic

​Implementation

​Usage Notes

​Get Call Details

​Endpoint

​Path Parameters

​Request

​cURL Example

​Response

​Success Response (200 OK)

​Error Response (404 Not Found)

​Implementation

​Usage Notes

Build docs developers (and LLMs) love

List Calls

Endpoint

Description

Request

cURL Example

Response

Success Response (200 OK)

Sorting Logic

Implementation

Usage Notes

Get Call Details

Endpoint

Path Parameters

Request

cURL Example

Response

Success Response (200 OK)

Error Response (404 Not Found)

Implementation

Usage Notes