> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesimple.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand the Simple AI Call Object

> Learn how Simple AI represents a phone call in the API, including its identifiers, status lifecycle, agent fields, transcript, and recording.

Every inbound and outbound call is represented by the same object in the API. This page explains the parts of it that are easy to misread: which identifier to use, what each status means, and how the agent fields relate to each other.

For the full list of fields, see [Get Call](/api-reference/calls/get-call).

## Identifiers

A call has one identifier, a UUID. It appears under different names depending on where you see it:

| Where | Field |
| - | - |
| [Create Call](/api-reference/calls/create-call) and [Cancel Call](/api-reference/calls/cancel-call) responses | `uuid` |
| [Get Call](/api-reference/calls/get-call) and [List Calls](/api-reference/calls/list-calls) | `id` and `simple_uuid` (the same value) |
| [Webhook](/webhooks) events | `call_id` |
| Paths such as `/calls/{uuid}` | `uuid` |

All of these hold the same value, so you can take the `uuid` from a create response or the `call_id` from a webhook and use it directly in any call endpoint.

To attach your own identifiers to a call, pass `external_identifiers` when you create it. You can then look the call up with [Find Call by Attribute](/api-reference/calls/find-by-attribute).

## Status

`status` tells you where a call is in its lifecycle.

| Status | Meaning |
| - | - |
| `enqueued` | An outbound call has been accepted and is waiting to be placed |
| `in_progress` | The call is being placed or the conversation is under way |
| `completed` | The call ended normally |
| `failed` | The call could not be placed or ended because of an error |
| `cancelled` | The call was cancelled before it started |

`completed`, `failed`, and `cancelled` are final. A call in one of these statuses does not change status again.

**Outbound calls** start as `enqueued` and move to `in_progress` when Simple AI places them. If your organization is already at its limit for simultaneous calls, new calls stay `enqueued` and are placed as earlier calls finish. You can [cancel](/api-reference/calls/cancel-call) a call while it is `enqueued`.

**Inbound calls** start as `in_progress`.

To see how an outbound call was answered, read `answered_by`: `human`, `voicemail`, `no_answer`, or `unknown`. It is `null` until that is known.

## Agent Fields

An agent has versions, and each version has a history of saved snapshots. A call records all three:

| Field | What it identifies |
| - | - |
| `agent_id` | The agent |
| `agent_branch` | The agent version the call ran on |
| `agent_branch_name` | The name of that version |
| `agent_commit_id` | The exact snapshot of that version used for the call |

These are `null` when the call is not associated with an agent.

The same IDs are used when you create and filter calls:

| To do this | Use |
| - | - |
| Create a call with an agent | `agent_id` |
| Create a call with a specific version of it | `agent_id` and `version_id` (the value returned as `agent_branch`) |
| List calls for an agent, across all its versions | the `agent_id` filter |
| List calls for one version | the `agent_version_id` filter (the value returned as `agent_branch`) |

When you create a call with `agent_id` and no `version_id`, the most recently updated version is used.

## Times

`created_at`, `updated_at`, `started_at`, and `ended_at` are ISO 8601 timestamps in UTC. `started_at` and `ended_at` are `null` until the call starts and ends. `duration` is the length of the call in seconds.

Each entry in `transcripts` has a `timestamp`, which is a Unix timestamp in seconds.

## Transcript, Recording, and Analysis

* **`transcripts`** — the conversation in order. Each entry has a `role`, the `text` that was said, and for tool calls a `function_name` and its `arguments`.
* **`recording_presigned_url`** — a temporary HTTPS link to the call audio, or `null` when there is no recording. Use the complete URL as returned, including its query parameters. Anyone with a valid link can access the recording until it expires, so request a fresh link each time rather than storing it.
* **`summary`** — a text summary of the call, when one is available.
* **`analyzers`** and **`analysis_results`** — the [analyzers](/analyzers) configured for the call and the results they have produced so far.
* **`tags`** — the [tags](/tags) applied to the call.

Recordings, summaries, and analysis results are produced after the call ends, so they can be missing when you first receive a `call.completed` webhook. Get the call again shortly afterwards to read them.

## Your Data on a Call

* **`params`** — the parameters passed when the call was created, plus any set during the call. See [Call Parameters](/calls#call-parameters).
* **`external_identifiers`** — the identifiers you attached when creating the call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.