List Calls

TypeScript

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();

{
  "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
      }
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

TypeScript

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();

{
  "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
      }
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

Authorizations

Authorization

string

header

required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Headers

x-phone

string

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.

Example:

"919876543210"

Query Parameters

offset

integer | null

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.

Required range: x >= 0

Example:

0

limit

integer

Maximum number of calls to return in one page. Cannot exceed 500. Defaults to 50.

Required range: 1 <= x <= 500

Example:

50

start_time

string

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"

end_time

string

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"

string

Case-insensitive text search across the chat name, chat_id, the AI summary and the transcript. Composes with the other filters.

Minimum string length: 1

Example:

"refund"

chat_id

string

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"

direction

enum<string>

Only return 'incoming' or 'outgoing' calls.

Available options:

incoming,

outgoing

Example:

"incoming"

result

string

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"

handled_via

enum<string>

'periskope' returns only calls answered or placed by a member in Periskope; 'phone' only calls handled (or missed) on the WhatsApp phone.

Available options:

periskope,

phone

Example:

"periskope"

has_recording

string

true/1/yes returns only recorded calls, false/0/no only calls without a recording (case-insensitive). Omit to return both.

Example:

"true"

transcript_status

string

Only return calls with this transcription status. Accepted values: pending, done, failed. Pass one value (done) or several, comma-separated (pending,failed).

Example:

"done"

member_email

string

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"

min_duration_seconds

number | null

Only return calls with at least this much talk time, in seconds. Calls with an unknown duration are excluded.

Required range: x >= 0

Example:

60

max_duration_seconds

number | null

Only return calls with at most this much talk time, in seconds. Calls with an unknown duration are excluded.

Required range: x >= 0

Example:

600

sort_order

enum<string>

Order by timestamp: 'desc' (newest first, the default) or 'asc' (oldest first, handy for syncing calls incrementally with start_time).

Available options:

asc,

desc

Example:

"desc"

Response

Paginated list of calls, newest first unless sort_order=asc

from

integer

1-based index of the first record in this page (offset + 1).

Example:

1

integer

1-based index of the last record in this page.

Example:

20

count

integer

Number of records in this page — the length of the calls array, not the total across all pages.

Example:

20

start_time

string

Echo of the start_time filter, present only when it was sent.

Example:

"2026-01-01T00:00:00Z"

end_time

string

Echo of the end_time filter, present only when it was sent.

calls

object[]

The calls in this page.

Show child attributes

API

Chat APIs

Group Settings APIs

Message APIs

Scheduled Message APIs

Call APIs

Media APIs

Contact APIs

Ticket APIs

Custom Property APIs

Task APIs

Queue APIs

Phone APIs

Notes APIs

Reaction APIs

Knowledge Base APIs

Member APIs

AI APIs

Webhook APIs

Webhooks

Authorizations

Headers

Query Parameters

Response