Skip to main content
After calls complete, Truedy stores a full record of every conversation — including the transcript, recording audio, duration, cost, and post-call analysis outcome. This guide covers how to query your call history, work with transcripts, access recordings, and export data for downstream systems.

​
Listing Calls

Use GET /calls to retrieve a paginated list of calls across your account. You can filter by agent, status, direction, or date range.

​
Endpoint

GET https://api.truedy.ai/api/public/v1/calls

​
Query Parameters

ParameterTypeDescription
agent_idstringFilter to calls handled by a specific agent
statusstringFilter by call status: queued, ringing, in-progress, ended, failed, cancelled
directionstringFilter by direction: outbound, inbound, webrtc
created_afterstringISO 8601 datetime — return only calls created after this time
created_beforestringISO 8601 datetime — return only calls created before this time
limitintegerNumber of records per page. Default: 20. Maximum: 100
offsetintegerNumber of records to skip for pagination. Default: 0

​
Response Structure

{
  "data": [
    { /* call object */ },
    { /* call object */ }
  ],
  "meta": {
    "total": 847,
    "limit": 20,
    "offset": 0
  }
}
The meta.total field gives the total number of calls matching your filters — use this with limit and offset to paginate through all results.

​
Getting a Single Call

Use GET /calls/{id} to fetch the complete record for one call by its ID.

​
Endpoint

GET https://api.truedy.ai/api/public/v1/calls/{call_id}

​
Code Examples

# List the 20 most recent ended calls for a specific agent
curl "https://api.truedy.ai/api/public/v1/calls?agent_id=agent_01hx2a7b3cd4ef5gh6ij7kl8mn&status=ended&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Working with Transcripts

The transcript field on a completed call is an ordered array of conversation turns. Each turn has three properties:
PropertyTypeDescription
speakerstringEither "agent" or "contact"
textstringThe words spoken in this turn
timestampnumberSeconds from the start of the call when this turn began

​
Example Transcript

[
  {
    "speaker": "agent",
    "text": "Hi Sarah, this is Aria calling from Bright Dental. How are you today?",
    "timestamp": 1.2
  },
  {
    "speaker": "contact",
    "text": "I'm good, thanks. What's this about?",
    "timestamp": 5.8
  },
  {
    "speaker": "agent",
    "text": "I'm calling to confirm your appointment on April 10th at 2 PM. Does that still work for you?",
    "timestamp": 9.1
  },
  {
    "speaker": "contact",
    "text": "Yes, that works perfectly.",
    "timestamp": 15.3
  }
]
Transcripts are generated asynchronously after the call ends. If you retrieve a call immediately after it completes, the transcript field may be null for a few seconds while processing finishes. The call.analyzed webhook event fires once the transcript is ready.

​
Extracting a Plain-Text Transcript

If you need to store or display the transcript as plain text, join the turns with speaker labels:
Python
def format_transcript(transcript):
    lines = []
    for turn in transcript:
        speaker = "Agent" if turn["speaker"] == "agent" else "Contact"
        lines.append(f"{speaker}: {turn['text']}")
    return "\n".join(lines)

​
Accessing Recordings

The recording_url field on an ended call contains a signed URL pointing to the MP3 audio recording of the conversation.
Recording URLs are time-limited. They expire after 24 hours. If you need to retain recordings long-term, download the audio file to your own storage (e.g. S3, GCS) promptly after the call ends or when you receive the call.analyzed webhook.

​
Downloading a Recording

# Download the recording to a local file
curl -L "https://recordings.truedy.ai/..." -o call_recording.mp3

​
Call Analytics Fields

In addition to the transcript and recording, each ended call includes analytics metadata:
FieldTypeDescription
duration_secondsintegerTotal call duration from answer to hang-up
cost_centsintegerCost of the call in USD cents. Useful for billing reconciliation
outcomestringPost-call analysis label applied by Truedy AI (e.g. interested, not-interested, voicemail, no-answer, callback-requested)
The outcome field is powered by Truedy’s post-call analysis and reflects the result of the conversation as determined by the AI. You can customise the outcome labels and logic in your agent’s configuration under Post-Call Analysis.

​
Pagination

The calls list endpoint returns up to 100 records per request. Use limit and offset to paginate through large result sets.
Python — Fetch all calls with pagination
import requests

def fetch_all_calls(**filters):
    all_calls = []
    offset = 0
    limit = 100

    while True:
        response = requests.get(
            "https://api.truedy.ai/api/public/v1/calls",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            params={"limit": limit, "offset": offset, **filters},
        )
        result = response.json()
        all_calls.extend(result["data"])

        if offset + limit >= result["meta"]["total"]:
            break

        offset += limit

    return all_calls

# Fetch every ended call from last week
calls = fetch_all_calls(
    status="ended",
    created_after="2024-04-01T00:00:00Z",
    created_before="2024-04-08T00:00:00Z",
)
print(f"Fetched {len(calls)} calls")

​
Filtering by Date

Use the created_after and created_before query parameters to narrow results to a specific time window. Both accept ISO 8601 datetime strings. 
# Calls from a specific day (UTC)
GET /calls?created_after=2024-04-05T00:00:00Z&created_before=2024-04-06T00:00:00Z

# Calls from the last 7 days (compute dynamically)
GET /calls?created_after=2024-03-29T00:00:00Z
All timestamps in the Truedy API are in UTC. Make sure to convert local times to UTC before constructing date filter parameters.

​
Exporting Call Data

Truedy does not currently provide a bulk CSV export endpoint. There are two recommended patterns for building your own export pipeline:

​
Pattern 1: Paginated API Pull

Write a script that paginates through GET /calls for your desired date range and writes results to a file or database. The Python pagination example above demonstrates this approach. Run it on a schedule (e.g. nightly) to keep an external data store up to date.

​
Pattern 2: Webhook + Store

For real-time exports, configure a call.analyzed webhook endpoint on your server. Each time a call completes, Truedy pushes the full call object — including transcript, outcome, and analytics — to your endpoint. Your server writes the record to your database, data warehouse, or CRM immediately. This pattern requires a publicly accessible server but avoids the need to poll the API.
For teams using CRMs or analytics tools, the webhook + store pattern is the most robust approach. It captures every call in real time and ensures you never miss a record due to pagination or timing issues.
See Webhooks Overview for webhook configuration details.

​
Data Retention

Truedy retains call records (metadata, transcripts) for 12 months from the call date. Recording audio files are available via signed URL for 24 hours after the call ends — after that, the link expires and the audio is no longer accessible through the API. If you need to retain recordings beyond 24 hours or call records beyond 12 months, implement your own archival process using the webhook + store pattern described above.

​
Next Steps

Calls Overview

Call statuses, directions, and lifecycle

Making Outbound Calls

Place individual outbound calls via the API

Webhooks Overview

Receive real-time call events on your server

Post-Call Analysis

Understand outcome labels and call summaries