> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt > Use this file to discover all available pages before exploring further. # List Calls > Calls on your number, newest first, cursor-paged. Scope: read. Calls on your number, newest first. Each item is a [call object](https://docs.flowapt.com/flowiq-api-reference/calling.md#the-call-object). ## Basic Usage ```bash theme={null} curl "https://api.flowiq.live/v1/calls?direction=inbound&since=2026-10-01&limit=50" \ -H "Authorization: Bearer fiq_YOUR_API_KEY" ``` *** ## Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `contact_id` | string | No | Only this contact's calls | | `direction` | string | No | `inbound` or `outbound` | | `since` | string | No | ISO date or time; calls that started at or after it | | `until` | string | No | ISO date or time; calls that started before it | | `status` | string | No | `ringing`, `in_progress`, `completed`, `missed`, `rejected` or `failed` | | `channel` | string | No | `whatsapp` or `phone` (calls to a FlowIQ phone line) | | `cursor` | string | No | `next_cursor` from the previous page | | `limit` | integer | No | Per page, default `25`, max `100` | *** ## Response ### Success (200) ```json theme={null} { "organization_id": "a4234f32-…", "data": [ { "id": "wacid.HBgLMjc4MjAwMDAwMDAVAgARGBI2RjQ3QkU1RjA5Q0UyMkEzQjQA", "channel": "whatsapp", "direction": "inbound", "status": "completed", "answered_by": "flowiq_ai", "from": "27820000000", "to": "15550001111", "started_at": "2026-09-23T21:17:16.983Z", "answered_at": "2026-09-23T21:17:22.000Z", "ended_at": "2026-09-23T21:20:51.000Z", "duration_seconds": 209, "end_reason": "completed", "transcript": "AI: Hi, thanks for calling…\nCaller: Hello…", "has_recording": false, "recording_url": null, "biz_opaque_callback_data": null, "contact": { "id": "9b8a7c6d-…", "whatsapp_id": "27820000000", "name": "Jane Doe" } } ], "pagination": { "limit": 50, "has_more": true, "next_cursor": "MjAyNi0wOS0yM1QyMToxNzoxNi45ODNafDFhMmIz…" } } ``` ## OpenAPI ````yaml flowiq-api-reference/openapi-calls.json GET /v1/calls openapi: 3.1.0 info: title: FlowIQ Calling API version: 1.0.0 description: >- Run WhatsApp calls on your FlowIQ number from your own server: answer, decline, end and start calls, ask for call permission, read call history and change the number's calling settings. Every response carries X-Request-Id; errors carry a stable code; POST / PATCH accept Idempotency-Key. servers: - url: https://api.flowiq.live description: FlowIQ Production API security: - BearerAuth: [] paths: /v1/calls: get: tags: - Calling summary: List Calls description: 'Calls on your number, newest first, cursor-paged. Scope: read.' operationId: listCalls parameters: - name: contact_id in: query required: false description: Only this contact's calls schema: type: string format: uuid - name: direction in: query required: false description: inbound or outbound schema: type: string enum: - inbound - outbound - name: status in: query required: false description: One status schema: type: string enum: - ringing - in_progress - completed - missed - rejected - failed - name: channel in: query required: false description: 'whatsapp (default: all) or phone' schema: type: string enum: - whatsapp - phone - name: since in: query required: false description: ISO date or time; calls that started at or after it schema: type: string example: '2026-10-01' - name: until in: query required: false description: ISO date or time; calls that started before it schema: type: string - name: limit in: query required: false description: Per page, default 25, max 100 schema: type: integer minimum: 1 maximum: 100 default: 25 - name: cursor in: query required: false description: next_cursor from the previous page schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: organization_id: type: string format: uuid data: type: array items: $ref: '#/components/schemas/Call' pagination: type: object properties: limit: type: integer has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as ?cursor= for the next page '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: schemas: Call: type: object properties: id: type: string description: >- WhatsApp's call id (starts with wacid.). URL-encode it when it goes in a path example: wacid.HBgLMjc4MjAwMDAwMDAVAgARGBI2RjQ3QkU1RjA5Q0UyMkEzQjQA channel: type: string enum: - whatsapp - phone description: >- whatsapp = WhatsApp call; phone = a call to a FlowIQ phone line (read only here) direction: type: string enum: - inbound - outbound status: type: string enum: - ringing - in_progress - completed - missed - rejected - failed answered_by: type: - string - 'null' enum: - api - stream - flowiq_ai - inbox - null description: >- Who picked up: your server (accept with an SDP answer), your server through the media stream, FlowIQ's voice AI, or a person in the FlowIQ inbox. null while nobody has started_at: type: string format: date-time answered_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time duration_seconds: type: - integer - 'null' example: 70 end_reason: type: - string - 'null' example: completed transcript: type: - string - 'null' description: >- Present when FlowIQ's voice AI answered, or a recording was transcribed has_recording: type: boolean recording_url: type: - string - 'null' description: Signed link to the recording, valid for 1 hour contact: type: - object - 'null' properties: id: type: string format: uuid description: FlowIQ contact id whatsapp_id: type: string description: WhatsApp number, digits only, with country code example: '27820000000' name: type: - string - 'null' example: Jane Doe from: type: - string - 'null' description: >- The caller's number (customer on inbound calls, your number on outbound) to: type: - string - 'null' biz_opaque_callback_data: type: - string - 'null' description: Your reference from accept / start, when you set one Error: type: object properties: error: type: string description: Short label (Bad request, Not found, …) code: type: string description: Stable machine-readable code, see Conventions message: type: string request_id: type: string format: uuid description: Quote this to support whatsapp_error_code: type: integer description: WhatsApp's own code, on whatsapp_rejected responses: BadRequest: description: Invalid request, or WhatsApp refused it (the message says why) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Request failed message: Parameter value is not valid Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the scope, or the person has not given call permission content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Request failed message: Contact has not granted callback permission RateLimited: description: 240 reads or 60 actions per minute per key; Retry-After says when content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: fiq_ API key description: >- Your FlowIQ organisation API key (Settings → API Keys), sent as a bearer token. Format: `Bearer fiq_YOUR_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.