Call history and recordings

GET /v1/calls is one feed of every call on your numbers: phone and WhatsApp, inbound and outbound, newest first. Each call record carries its duration, end reason, cost, and the recording and transcript when those were on.

#Read from one place, act on the channel

#List calls

curl "https://api.pozy.ai/v1/calls?direction=inbound&status=ended&limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"

let before: string | undefined;
do {
  const query = new URLSearchParams({ limit: "100" });
  if (before) query.set("before", before);
  const res = await fetch(`https://api.pozy.ai/v1/calls?${query}`, {
    headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error);
  for (const c of data.calls) console.log(c.channel, c.direction, c.status, c.durationSeconds, c.contactName);
  before = data.nextCursor ?? undefined;
} while (before);

import os, requests

params = {"limit": 100}
while True:
    page = requests.get(
        "https://api.pozy.ai/v1/calls",
        headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
        params=params,
        timeout=30,
    ).json()
    for c in page["calls"]:
        print(c["channel"], c["direction"], c["status"], c.get("durationSeconds"))
    if not page["nextCursor"]:
        break
    params["before"] = page["nextCursor"]

List rows leave out the full transcript. lastTranscriptSnippet is a preview.

#Open one call

GET /v1/calls/{id} returns the full record for a call on either channel.

{
  "call": {
    "_id": "66e5f6a7b8c9d0e1f2a3b4c5",
    "channel": "pstn",
    "direction": "inbound",
    "from": "+13125550188",
    "to": "+14155550142",
    "status": "ended",
    "endReason": "hangup",
    "durationSeconds": 184,
    "isVoicemail": false,
    "recordingEnabled": true,
    "transcriptionEnabled": true,
    "transcript": [
      { "text": "Hi, I am calling about order 1234.", "confidence": 0.96, "at": "2026-10-30T09:00:06Z" }
    ],
    "billing": { "billableCostUSD": 0.135, "currency": "USD" },
    "conversationId": "66c3d2ae7b4f6c8d0e1f2a3b"
  }
}

#Get the recording

recordingUrl on a call record is signed and expires about 10 minutes after it is issued. For a fresh link, call GET /v1/calls/{id}/recording. By default it redirects (302) to a playable MP3. Add as=json to get { "url": "..." } instead.

curl "https://api.pozy.ai/v1/calls/66e5f6a7b8c9d0e1f2a3b4c5/recording?as=json" \
  -H "Authorization: Bearer $POZY_API_KEY"

Fetch the link when someone presses play rather than storing it. If you need to keep recordings, download the file and store it yourself.

#Turn recording and transcription on

Both are off by default. Set them on the number for every call, or per call when you dial out.

Recording never starts silently: on bridged calls a consent notice plays first. A recording exists only if recording was on when the call started. Voicemail messages are recorded whenever voicemail takes a call.

#What it costs

Recording and transcription are billed per minute on top of the call. See the usage table on Phone numbers or Pricing.

#Get calls pushed instead of polling

call.ended carries the finished call (duration, end reason, cost, and a signed recordingUrl with recordingExpiresAt when recording was on). The transcript is not in the event: fetch the call record when you need it.

#Errors

#Endpoints