---
title: "List the calls"
method: GET
path: "/calls"
tags: ["Calls"]
---

# List the calls

`GET /calls`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/calls`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `calls:read`)

The calls of the project, inbound and outbound, newest first, without transcript and summary. Follow next_cursor while has_more is true. A call your assistant made with POST /calls has direction outbound and an outbound object with its status, reference and metadata.

## Query parameters

- `limit` integer
- `cursor` string
- `direction` 'inbound' | 'outbound'

## Response `200`

A page of calls.

- CallList
  - `data` Call[], required
    - `id` string, uuid, required: The id of the call.
    - `direction` 'inbound' | 'outbound' | 'null', nullable, required: inbound, or outbound for a call your assistant made with POST /calls.
    - `from` string, nullable, required: The caller, in E.164.
    - `to` string, nullable, required: The number that was called, in E.164.
    - `status` string, nullable, required: The status as we track it: ringing, active, completed, missed, failed, voicemail, ai_handled. New values may be added; treat an unknown value like completed.
    - `created_at` string, date-time, nullable, required: When the call reached us.
    - `started_at` string, date-time, nullable, required: When the call started.
    - `answered_at` string, date-time, nullable, required: When the platform picked up. With a call plan the platform always picks up first, so this does not prove a person answered.
    - `ended_at` string, date-time, nullable, required: When the call ended.
    - `duration_sec` integer, nullable, required: The length of the call in seconds.
    - `hangup_cause` string, nullable, required: Why the call ended, as reported by the carrier, like normal_clearing.
    - `has_summary` boolean, required: Whether the call has a summary. Fetch it with GET /calls/{id}.
    - `summary_ready_at` string, date-time, nullable, required: When the summary of a recorded call was ready. Empty for a call handled by the voice AI; look at has_summary instead.
    - `test` boolean, required: true for a simulated call from POST /test/calls or POST /calls with a test key (test mode). Also in webhooks, so you can keep test traffic apart.
    - `outbound` object, nullable, required: The request behind an outbound call started with POST /calls.
      - `status` 'queued' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'no_answer' | 'busy', required: How the outbound call went: queued (not dialled yet), ringing, in_progress (answered), completed, failed, no_answer or busy. An answering machine counts as no_answer, with answered_by machine. Only moves forward.
      - `answered_by` 'human' | 'machine' | 'null', nullable, required: Who picked up, as far as answering machine detection could tell; null when nobody answered or before it is known.
      - `voicemail_left` boolean, required: Whether the assistant left a message on an answering machine.
      - `on_voicemail` 'hangup' | 'leave_message', required: What you asked the assistant to do when an answering machine picks up.
      - `max_duration_sec` integer, required: The cap on the length of the call you asked for, in seconds.
      - `reference` string, nullable, required: Your own reference from POST /calls.
      - `metadata` object, required: Your own metadata from POST /calls.
      - `error` string, nullable, required: With status failed: a short code, like carrier_rejected, assistant_start_failed or unallocated_number. Otherwise null.
      - `purpose` 'transactional' | 'marketing', required: Why the call was made, as sent with POST /calls (transactional when left out). A marketing call was only placed on recorded consent.
  - `has_more` boolean, required: Whether there is a next page.
  - `next_cursor` string, nullable, required: Pass this as cursor to get the next page. Null on the last page.

## Other responses

- `400`: Bad Request: invalid_parameter.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)