---
title: "Get the timeline of a call"
method: GET
path: "/calls/{id}/events"
tags: ["Calls"]
---

# Get the timeline of a call

`GET /calls/{id}/events`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/calls/{id}/events`
- 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`)

What happened in one call: its legs (the caller, and every forward by the call plan to a number or to the app or web phone of a member), the events per leg in order (started, answered, ended), the outcome the way the portal says it (answered, missed, no_answer, voicemail, assistant, in_progress, failed) and who on your side picked up (answered_by). The id can be any leg of the call that GET /calls lists.

## Path parameters

- `id` string, uuid, required

## Response `200`

The timeline.

- CallTimeline: The timeline of a call: its legs, its events, the outcome and who answered.
  - `call_id` string, uuid, required: The call you asked for.
  - `outcome` 'answered' | 'missed' | 'no_answer' | 'voicemail' | 'assistant' | 'in_progress' | 'failed' | 'unknown', required: How the call went, the same way the portal says it: answered, missed (inbound and nobody picked up), no_answer (outbound and nobody picked up), voicemail, assistant (the voice AI handled it), in_progress, failed or unknown.
  - `answered_by` union, required: Who on your side picked up: the first forward that was answered, else the assistant when it handled the call, else null.
    - union
      - object
        - `type` 'number', required
        - `number` string, nullable, required: The number the call was forwarded to, in E.164.
      - object
        - `type` 'device', required
        - `user_id` string, nullable, required: The member whose app or web phone it was (the user_id from list_members), or null when it is not known.
    - object
      - `type` 'assistant', required
  - `legs` object[], required: The legs, primary first, then the forwards oldest first.
    - `leg_id` string, uuid, required: The id of this leg. For the primary leg and a forward to a number this is also a call id in GET /calls.
    - `role` 'primary' | 'forward', required: primary: the caller (inbound) or the person called (outbound). forward: a forward by the call plan or a transfer.
    - `direction` 'inbound' | 'outbound' | 'null', nullable, required: The direction of this leg.
    - `target` union, required: Where a forward went. Null for the primary leg.
      - object
        - `type` 'number', required
        - `number` string, nullable, required: The number the call was forwarded to, in E.164.
      - object
        - `type` 'device', required
        - `user_id` string, nullable, required: The member whose app or web phone it was (the user_id from list_members), or null when it is not known.
    - `status` string, nullable, required: The status of this leg, like the status of a call.
    - `started_at` string, date-time, nullable, required: When this leg started ringing.
    - `answered_at` string, date-time, nullable, required: When this leg was answered.
    - `ended_at` string, date-time, nullable, required: When this leg ended.
    - `hangup_cause` string, nullable, required: Why this leg ended, as reported by the carrier, like normal_clearing or timeout.
  - `events` object[], required: What happened, oldest first.
    - `type` 'call.started' | 'call.answered' | 'call.ended' | 'forward.started' | 'forward.answered' | 'forward.ended', required: call.started, call.answered (the platform picked up; with a call plan it always does first), call.ended, and per forward forward.started, forward.answered (someone picked up there) and forward.ended.
    - `occurred_at` string, date-time, required: When it happened.
    - `leg_id` string, uuid, required: The leg it happened on (legs[].leg_id).
    - `hangup_cause` string, nullable: Only on call.ended and forward.ended.

## Other responses

- `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.
- `404`: Not Found: not_found.
- `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)