Skip to main content
GET
cURL
Returns one customer’s recent calls as a plain JSON array, ordered newest first by creation time. An empty history returns []. customerId is your external customer reference — the same identifier accepted by the customerId filter on List All Calls and by the Scheduled Calls customer routes — not a Finosu call or customer UUID. An unknown reference, or a deleted customer, returns 404.

Scope

The response covers only calls created in the last 30 days. Deleted calls and dial attempts that never progressed past the initial attempted state are excluded. For the full history, including older calls and unconnected attempts, use List All Calls, which has no date cutoff.

Pagination

limit (1–1000) and offset (default 0) slice the newest-first list; omit limit to return every call in the 30-day window. There is no cursor, so calls created between requests shift offsets. Values outside these ranges return 422.

Response fields

Each item has the same shape as Retrieve a Call: customerId echoes your external reference, falling back to the Finosu customer UUID when no reference is stored. timestamp is the call record’s creation time in ISO 8601. recordingUrl is a fresh link valid for one hour, or null when the call has no recording or recording storage is temporarily unavailable. Unlike the bulk listing, recording links are included per item, so large pages respond more slowly.

Errors

Errors use FastAPI’s detail field: a string for 404, an array of field errors for 422.

Authorizations

X-API-Key
string
header
required

Path Parameters

customerId
string
required

External customer reference ID

Query Parameters

limit
integer

The maximum number of results to return

Required range: 1 <= x <= 1000
offset
integer
default:0

The offset of the first result to return

Required range: x >= 0

Response

Calls response

customerId
string
required

Your external customer reference, falling back to the Finosu customer UUID when no reference is stored.

toPhoneNumber
string | null

Called phone number, or null when unavailable.

transcript
string | null

Call transcript, or null when unavailable.

recordingUrl
string | null

Fresh one-hour recording URL, or null when unavailable.

timestamp
string | null

Call record creation time in ISO 8601 format, or null.