> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # List Calls > Returns the organization's call history, newest first, with recording links and AI summaries for calls handled in Periskope. Use Get a call for the transcript. ## OpenAPI ````yaml api-reference/openapi-generated.json GET /v1/calls openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/calls: get: tags: - Calls summary: List calls description: >- Returns the organization's call history, newest first, with recording links and AI summaries for calls handled in Periskope. Use Get a call for the transcript. operationId: listCalls parameters: - schema: type: integer nullable: true minimum: 0 description: >- Number of records to skip before the first returned record. Use together with limit to paginate: page N is offset = N * limit. Defaults to 0. example: 0 required: false description: >- Number of records to skip before the first returned record. Use together with limit to paginate: page N is offset = N * limit. Defaults to 0. name: offset in: query - schema: type: integer minimum: 1 maximum: 500 description: >- Maximum number of calls to return in one page. Cannot exceed 500. Defaults to 50. example: 50 required: false description: >- Maximum number of calls to return in one page. Cannot exceed 500. Defaults to 50. name: limit in: query - schema: type: string description: >- Only return records at or after this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision. example: '2026-01-01T00:00:00Z' required: false description: >- Only return records at or after this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision. name: start_time in: query - schema: type: string description: >- Only return records at or before this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision. example: '2026-01-31T23:59:00Z' required: false description: >- Only return records at or before this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision. name: end_time in: query - schema: type: string minLength: 1 description: >- Case-insensitive text search across the chat name, chat_id, the AI summary and the transcript. Composes with the other filters. example: refund required: false description: >- Case-insensitive text search across the chat name, chat_id, the AI summary and the transcript. Composes with the other filters. name: q in: query - schema: type: string description: >- Only return calls in these chats. A single chat_id or a comma-separated list. For 1-1 chats, country code + number optionally suffixed with @c.us (the suffix is added automatically when omitted); for groups, the id ending with @g.us. example: 919999999999@c.us required: false description: >- Only return calls in these chats. A single chat_id or a comma-separated list. For 1-1 chats, country code + number optionally suffixed with @c.us (the suffix is added automatically when omitted); for groups, the id ending with @g.us. name: chat_id in: query - schema: type: string enum: - incoming - outgoing description: Only return 'incoming' or 'outgoing' calls. example: incoming required: false description: Only return 'incoming' or 'outgoing' calls. name: direction in: query - schema: type: string description: >- Only return calls with this result. Accepted values: connected, missed, rejected, unavailable, cancelled, acceptedelsewhere, invalid, upcoming, failed, abandoned, ongoing. Pass one value (missed) or several, comma-separated (missed,rejected). example: missed required: false description: >- Only return calls with this result. Accepted values: connected, missed, rejected, unavailable, cancelled, acceptedelsewhere, invalid, upcoming, failed, abandoned, ongoing. Pass one value (missed) or several, comma-separated (missed,rejected). name: result in: query - schema: type: string enum: - periskope - phone description: >- 'periskope' returns only calls answered or placed by a member in Periskope; 'phone' only calls handled (or missed) on the WhatsApp phone. example: periskope required: false description: >- 'periskope' returns only calls answered or placed by a member in Periskope; 'phone' only calls handled (or missed) on the WhatsApp phone. name: handled_via in: query - schema: type: string description: >- true/1/yes returns only recorded calls, false/0/no only calls without a recording (case-insensitive). Omit to return both. example: 'true' required: false description: >- true/1/yes returns only recorded calls, false/0/no only calls without a recording (case-insensitive). Omit to return both. name: has_recording in: query - schema: type: string description: >- Only return calls with this transcription status. Accepted values: pending, done, failed. Pass one value (done) or several, comma-separated (pending,failed). example: done required: false description: >- Only return calls with this transcription status. Accepted values: pending, done, failed. Pass one value (done) or several, comma-separated (pending,failed). name: transcript_status in: query - schema: type: string description: >- Only return calls these members were on (answered, placed or joined in Periskope). A single email or a comma-separated list, matched case-insensitively. Calls handled on the phone have no members and never match. example: agent@example.com required: false description: >- Only return calls these members were on (answered, placed or joined in Periskope). A single email or a comma-separated list, matched case-insensitively. Calls handled on the phone have no members and never match. name: member_email in: query - schema: type: number nullable: true minimum: 0 description: >- Only return calls with at least this much talk time, in seconds. Calls with an unknown duration are excluded. example: 60 required: false description: >- Only return calls with at least this much talk time, in seconds. Calls with an unknown duration are excluded. name: min_duration_seconds in: query - schema: type: number nullable: true minimum: 0 description: >- Only return calls with at most this much talk time, in seconds. Calls with an unknown duration are excluded. example: 600 required: false description: >- Only return calls with at most this much talk time, in seconds. Calls with an unknown duration are excluded. name: max_duration_seconds in: query - schema: type: string enum: - asc - desc description: >- Order by timestamp: 'desc' (newest first, the default) or 'asc' (oldest first, handy for syncing calls incrementally with start_time). example: desc required: false description: >- Order by timestamp: 'desc' (newest first, the default) or 'asc' (oldest first, handy for syncing calls incrementally with start_time). name: sort_order in: query - schema: type: string example: '919876543210' description: >- Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access. required: false description: >- Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access. name: x-phone in: header responses: '200': description: Paginated list of calls, newest first unless sort_order=asc content: application/json: schema: type: object properties: from: type: integer description: >- 1-based index of the first record in this page (offset + 1). example: 1 to: type: integer description: 1-based index of the last record in this page. example: 20 count: type: integer description: >- Number of records in this page — the length of the `calls` array, not the total across all pages. example: 20 start_time: type: string description: >- Echo of the start_time filter, present only when it was sent. example: '2026-01-01T00:00:00Z' end_time: type: string description: >- Echo of the end_time filter, present only when it was sent. calls: type: array items: $ref: '#/components/schemas/CallSummary' description: The calls in this page. examples: default: summary: Response body value: from: 1 to: 20 count: 20 start_time: '2026-01-01T00:00:00Z' end_time: null calls: - call_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA notification_id: >- false_919999999999@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_919999999999@c.us org_id: 00000000-0000-0000-0000-000000000000 org_phone: 911111111111@c.us chat_id: 919999999999@c.us chat_name: John Doe caller: 919999999999@c.us direction: incoming result: connected handled_via: periskope timestamp: '2026-01-15T09:30:00.000Z' duration_seconds: 184 answered_by: agent@example.com transcript: status: done summary: text: >- The customer asked about a delayed order. The agent confirmed it ships tomorrow and shared the tracking link. recording: url: >- https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... url_expires_at: '2026-01-15T10:30:00.000Z' duration_seconds: 184 '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: '919876543210', // the phone to act with (x-phone) }); async function main() { const response = await client.calls.listCalls(); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X GET 'https://api.periskope.app/v1/calls' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' components: schemas: CallSummary: type: object properties: call_id: type: string description: >- WhatsApp's id for the call. Pass it to Get a call. Also the unique_id of the call's notification row. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA notification_id: type: string description: >- Id of the call's row in the notifications list (type "call") and in chat.notification.created webhook events. Get a call also accepts it in place of call_id. example: >- false_919999999999@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_919999999999@c.us org_id: type: string format: uuid description: Id of the organization the call belongs to. example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) that made or received the call, as country code + number suffixed with @c.us. example: 911111111111@c.us chat_id: type: string description: >- Chat the call belongs to: the other party for a 1-1 call, the group for a group call. A caller WhatsApp could not resolve to a number appears as an id ending in @lid. example: 919999999999@c.us chat_name: type: string description: >- Name of the chat, or the contact's saved name when the chat has none. Absent for unknown numbers. example: John Doe caller: type: string description: >- Who placed the call (@c.us): the org phone for outgoing calls, the customer for incoming ones. example: 919999999999@c.us direction: type: string enum: - incoming - outgoing description: '''incoming'' or ''outgoing'', from the org phone''s point of view.' example: incoming result: type: string description: >- How the call ended, as reported by WhatsApp. One of: connected, missed, rejected, unavailable, cancelled, acceptedelsewhere, invalid, upcoming, failed, abandoned, ongoing. Absent for very old calls. example: connected handled_via: type: string enum: - periskope - phone description: >- 'periskope' when the call's audio ran through Periskope (answered or placed by a member in the app); 'phone' otherwise — answered, placed or missed on the WhatsApp phone itself. Only Periskope calls have a recording, transcript and summary. example: periskope timestamp: type: string description: >- When the call was logged, as an ISO 8601 UTC timestamp — the call start for most calls. Calls are sorted by this field. example: '2026-01-15T09:30:00.000Z' duration_seconds: type: number description: >- Talk time in seconds (0 for unanswered calls), when known — from WhatsApp, or the recording length otherwise. example: 184 answered_by: type: string description: >- Email of the member who answered (incoming) or placed (outgoing) the call in Periskope. example: agent@example.com transcript: type: object properties: status: type: string description: >- Transcription progress: 'pending' (queued or running), 'done' or 'failed'. Transcription starts once the recording is saved and usually finishes within a few minutes of the call ending. example: done description: >- Transcription status. Absent when the call was not recorded. Get a call returns the transcript itself. summary: type: object properties: text: type: string description: Two to three sentence summary of the conversation. example: >- The customer asked about a delayed order. The agent confirmed it ships tomorrow and shared the tracking link. description: >- AI summary of the call, generated after transcription. Absent until then, or when summarizing failed. recording: $ref: '#/components/schemas/CallRecordingSummary' description: >- A call as listed by List calls. Get a call returns the full Call: timing details, participants, per-member recordings and the transcript. CallRecordingSummary: type: object properties: url: type: string description: >- Downloadable link to the call recording, a stereo WAV file. When the organization's media privacy is on, the link carries an access token, opens without other credentials and stops working 1 hour after the response (url_expires_at); fetch the call again for a fresh link. When media privacy is off, it is a plain link that opens without credentials and does not expire. example: >- https://api.periskope.app/app/media/periskope-call-attachments/00000000-0000-0000-0000-000000000000/phone-aaaaaaaaaaaaaaaa/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.wav?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... url_expires_at: type: string description: >- When url (and every agent_tracks url) stops working, as an ISO 8601 UTC timestamp: 1 hour after the response. Present only when the organization's media privacy is on; without it the links do not expire. example: '2026-01-15T10:30:00.000Z' duration_seconds: type: integer description: Length of the recording in seconds. example: 184 description: >- The call recording with a downloadable link. Absent when the call was not recorded (handled on the phone, unanswered, or too short). securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.