> ## Documentation Index > Fetch the complete documentation index at: https://docs.finosu.com/llms.txt > Use this file to discover all available pages before exploring further. # List All Calls > Retrieve your company’s call history with cursor pagination. Use `GET /calls` to retrieve call records across all customers in the company associated with your `X-API-Key`. No customer ID is required, and there is no default date cutoff. The response includes inbound calls, outbound calls, uploaded recordings, and unsuccessful attempts, including records still being processed. Test-customer calls are included. Deleted calls, calls belonging to deleted customers, and legacy calls without a creation timestamp are excluded. For calls made to borrowers, use `callType=OUTBOUND`. Future scheduled calls are available through the [Scheduled Calls API](/api-reference/endpoint/scheduled-calls/get). ## First request ```bash theme={null} curl --fail-with-body --get 'https://api.finosu.com/calls' \ --header "X-API-Key: $FINOSU_API_KEY" \ --data-urlencode 'limit=50' \ --data-urlencode 'callType=OUTBOUND' ``` ```json theme={null} { "calls": [ { "id": "c2790fa1-d9aa-4510-b80b-22e0c4b94a4e", "customerId": "customer-123", "fromPhoneNumber": "+15550000001", "toPhoneNumber": "+15550000002", "timestamp": "2026-09-01T12:00:00Z", "callType": "OUTBOUND", "status": "CALL_ENDED", "callResult": "CONNECTED", "duration": 60, "transcript": "Example conversation transcript." } ], "nextCursor": null } ``` `id` is the stable Finosu call UUID, also accepted by [Get Call by ID](/api-reference/endpoint/calls/get-by-id). `customerId` is your external customer reference, falling back to the Finosu customer UUID when no reference is stored. `duration` is in seconds. `timestamp` is the call record's creation time. `status` describes its processing stage; `callResult` describes its outcome. Outcomes, duration, transcripts, and phone numbers can be `null` when unavailable. Fetch a call by ID for its recording link; recordings are omitted from the bulk listing so exports do not require a storage lookup for every call. Recording links expire after one hour and can be refreshed by fetching the call again. ## Retrieve every page Calls are ordered newest first by creation time, then call UUID to break ties. `limit` defaults to 50 and accepts 1–100. Pagination happens in the database. The endpoint allows 60 requests per 60-second window per company, shared across its API keys. If the quota is exhausted (`429`) or its enforcement is temporarily unavailable (`503`), wait for the `Retry-After` interval before retrying the same page. When `nextCursor` contains a string, pass that exact value as the next request's `cursor`. Keep the same API-key company and filters on every page; you may change `limit`. Treat cursors as opaque and URL-encode them. A `null` cursor means the export is complete. An empty result is `{"calls": [], "nextCursor": null}`. This Python example writes one call per line to a private JSON Lines file without accumulating the entire history in memory or logging call data. It requires the `requests` package, a `FINOSU_API_KEY` environment variable, and `FINOSU_CALL_EXPORT_PATH` set to a new file in an access-controlled directory. On POSIX systems, the file is readable and writable only by its owner; on other systems, configure equivalent directory permissions. The example refuses to overwrite an existing file. Treat the export as sensitive data: it contains customer identifiers, phone numbers, and transcripts. The example retries `429` and `503` responses up to four times per page, respecting `Retry-After`. A failed request can leave a partial export. ```python theme={null} import json import os import requests from requests.adapters import HTTPAdapter from urllib3.util import Retry params = {"limit": 100} # Add "callType": "OUTBOUND" for outbound calls only. export_fd = os.open( os.environ["FINOSU_CALL_EXPORT_PATH"], os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, ) with os.fdopen(export_fd, "w", encoding="utf-8") as output, requests.Session() as session: session.headers["X-API-Key"] = os.environ["FINOSU_API_KEY"] session.mount( "https://api.finosu.com/", HTTPAdapter(max_retries=Retry( total=4, allowed_methods={"GET"}, status_forcelist={429, 503}, backoff_factor=1, respect_retry_after_header=True, )), ) while True: response = session.get( "https://api.finosu.com/calls", params=params, timeout=60 ) response.raise_for_status() page = response.json() for call in page["calls"]: output.write(json.dumps(call) + "\n") if page["nextCursor"] is None: break params["cursor"] = page["nextCursor"] ``` Newer calls created during pagination appear in a fresh traversal; they do not shift subsequent pages. This is a live history, not a frozen snapshot: existing call outcomes and artifacts can change as processing finishes, and backfilled or deleted records can change the available history. Deduplicate exports by `id`. Use [call webhooks](/api-reference/endpoint/calls/webhook) for completed-call updates, or reread an overlapping creation-time window to refresh recent records. ## Filter the history All filters are optional and combined: | Parameter | Meaning | | - | - | | `customerId` | Exact external customer reference (the same identifier used by the customer-specific route). | | `callType` | `INBOUND`, `OUTBOUND`, or `UPLOAD`. Omit for all types. | | `createdAfter` | Inclusive creation-time lower bound, such as `2026-09-01T00:00:00Z`. | | `createdBefore` | Exclusive creation-time upper bound, such as `2026-10-01T00:00:00Z`. | Dates must include a timezone (`Z` or an explicit offset). `createdAfter` must precede `createdBefore`. These filters use creation time, not last-updated time. Unknown customer references return an empty list. ```bash theme={null} curl --fail-with-body --get 'https://api.finosu.com/calls' \ --header "X-API-Key: $FINOSU_API_KEY" \ --data-urlencode 'callType=OUTBOUND' \ --data-urlencode 'createdAfter=2026-09-01T00:00:00Z' \ --data-urlencode 'createdBefore=2026-10-01T00:00:00Z' ``` ## Errors | Status | Meaning | | - | - | | `400` | Invalid cursor, cursor from a different company/filter set, or invalid date range. | | `401` | Missing, invalid, inactive, deleted, or empty API key. | | `422` | Invalid query value, including limits outside 1–100 or dates without timezones. | | `429` | Company request quota exhausted. Retry the same page after the `Retry-After` interval (60 seconds). | | `503` | Request quota enforcement is temporarily unavailable. Retry the same page after the `Retry-After` interval (60 seconds). | Errors use FastAPI's `detail` field. Validation errors contain an array of field errors; authentication, cursor/range, and quota errors contain a string. Existing call-by-ID and customer-specific routes retain their current response shapes. ## OpenAPI ````yaml GET /calls openapi: 3.1.0 info: title: Finosu API description: Finosu API license: name: MIT version: 1.0.0 servers: - url: https://api.finosu.com security: - apiKeyAuth: [] paths: /calls: get: summary: List all calls description: >- Returns call history across the authenticated company, ordered by creation time and call UUID descending. Includes all dates, call types, test customers, processing stages, and unsuccessful attempts. Deleted calls/customers and legacy calls without a creation timestamp are excluded. Limited to 60 requests per 60 seconds per company across all API keys. Exceeded quotas return 429; quota-service outages return 503. Both include Retry-After: 60. Follow nextCursor until null; keep filters unchanged. Cursors do not provide snapshot isolation. operationId: listCalls parameters: - name: limit in: query required: false description: Maximum records per page. Default 50; range 1–100. schema: type: integer default: 50 minimum: 1 maximum: 100 - name: cursor in: query required: false description: >- Opaque nextCursor from the preceding response. Keep the same company and filters. schema: type: string minLength: 1 maxLength: 2048 - name: customerId in: query required: false description: >- Exact external customer reference. Unknown references return an empty list. schema: type: string minLength: 1 maxLength: 255 - name: callType in: query required: false description: Filter by call type; omit for all types. schema: type: string enum: - INBOUND - OUTBOUND - UPLOAD - name: createdAfter in: query required: false description: >- Inclusive creation-time lower bound. Must include a timezone and precede createdBefore. schema: type: string format: date-time - name: createdBefore in: query required: false description: Exclusive creation-time upper bound. Must include a timezone. schema: type: string format: date-time responses: '200': description: A page of calls, newest first. nextCursor is null on the last page. content: application/json: schema: $ref: '#/components/schemas/CallListResponse' '400': description: >- Invalid cursor, changed cursor scope or filters, or invalid date range. content: application/json: schema: type: object required: - detail properties: detail: type: string '401': description: Missing, invalid, inactive, deleted, or empty API key. content: application/json: schema: type: object required: - detail properties: detail: type: string '422': description: Invalid query parameter. content: application/json: schema: type: object required: - detail properties: detail: type: array items: type: object required: - loc - msg - type properties: loc: type: array items: oneOf: - type: string - type: integer msg: type: string type: type: string '429': description: Company quota exceeded. Retry after the indicated number of seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 Cache-Control: schema: type: string const: no-store content: application/json: schema: type: object required: - detail properties: detail: type: string '503': description: >- Quota verification is unavailable. Retry after the indicated number of seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 Cache-Control: schema: type: string const: no-store content: application/json: schema: type: object required: - detail properties: detail: type: string security: - apiKeyAuth: [] components: schemas: CallListResponse: type: object required: - calls - nextCursor properties: calls: type: array items: $ref: '#/components/schemas/CallListItem' nextCursor: type: - string - 'null' description: Opaque continuation cursor, or null when no more records remain. CallListItem: type: object required: - id - customerId - fromPhoneNumber - toPhoneNumber - timestamp - callType - status - callResult - duration - transcript properties: id: type: string format: uuid description: Stable Finosu call ID, accepted by GET /calls/{id}. customerId: type: string description: External customer reference, or Finosu customer UUID when absent. fromPhoneNumber: type: - string - 'null' description: Caller phone number when available. toPhoneNumber: type: - string - 'null' description: Callee phone number when available. timestamp: type: string format: date-time description: Call record creation time. callType: type: string enum: - INBOUND - OUTBOUND - UPLOAD status: type: string description: Current call processing stage. example: CALL_ENDED callResult: type: - string - 'null' description: Call outcome when available. example: CONNECTED duration: type: - integer - 'null' description: Call duration in seconds when available. transcript: type: - string - 'null' description: Call transcript when available. securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key ````