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

# Calls

> List, search, retrieve, trigger, and delete calls, plus transcripts and recordings.

Base path: `https://api.recepta.ai/api/v1/api/calls`

All endpoints require an [API key](/api-reference/authentication) in `x-api-key`, and the permission noted on each.

## List calls

<ParamField path="GET /api/v1/api/calls" type="calls:read" required />

| Query param | Type    | Notes          |
| ----------- | ------- | -------------- |
| `page`      | integer | Page number    |
| `limit`     | integer | Items per page |

```bash theme={null}
curl "https://api.recepta.ai/api/v1/api/calls?page=1&limit=20" \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Search calls

<ParamField path="GET /api/v1/api/calls/search" type="calls:read" required />

| Query param | Type   | Notes                 |
| ----------- | ------ | --------------------- |
| `q`         | string | Search query          |
| `status`    | string | Filter by call status |

```bash theme={null}
curl "https://api.recepta.ai/api/v1/api/calls/search?q=water+heater" \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Call analytics

<ParamField path="GET /api/v1/api/calls/analytics" type="analytics:read" required />

| Query param | Type | Notes        |
| ----------- | ---- | ------------ |
| `startDate` | date | `YYYY-MM-DD` |
| `endDate`   | date | `YYYY-MM-DD` |

```bash theme={null}
curl "https://api.recepta.ai/api/v1/api/calls/analytics?startDate=2026-07-01&endDate=2026-07-31" \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Get a call

<ParamField path="GET /api/v1/api/calls/{callId}" type="calls:read" required />

Returns `404` if the call doesn't exist in your workspace.

```bash theme={null}
curl https://api.recepta.ai/api/v1/api/calls/CALL_ID \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Create a web call

<ParamField path="POST /api/v1/api/calls/web" type="calls:create" required />

Starts a browser-based call rather than dialing a phone number.

<ResponseField name="agentId" type="string">
  Agent to handle the call. Falls back to your default agent if omitted.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary data attached to the call record.
</ResponseField>

Returns `201` on success.

## Trigger an outbound call

<ParamField path="POST /api/v1/api/calls/outbound" type="calls:create" required />

Dials a phone number using one of your agents. `POST /api/v1/api/calls/phone` is the equivalent underlying endpoint.

<ResponseField name="toNumber" type="string" required>
  Number to call, E.164 — e.g. `+14155551234`.
</ResponseField>

<ResponseField name="fromNumber" type="string" required>
  One of your own provisioned numbers to call from.
</ResponseField>

<ResponseField name="agentId" type="string">
  Agent to use. Falls back to your default agent if omitted.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary data attached to the call record.
</ResponseField>

```bash theme={null}
curl -X POST https://api.recepta.ai/api/v1/api/calls/outbound \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+14155551234",
    "fromNumber": "+14155559876",
    "metadata": { "campaign": "q3-quotes" }
  }'
```

Returns `201` on success, or `429` if your plan's call limit is exhausted.

<Warning>
  Outbound calling is subject to calling-hour restrictions, do-not-call obligations, and consent requirements in the called party's jurisdiction. See [Recording & consent](/phone/recording-and-consent).
</Warning>

## Get a transcript

<ParamField path="GET /api/v1/api/calls/{callId}/transcript" type="calls:transcript" required />

```bash theme={null}
curl https://api.recepta.ai/api/v1/api/calls/CALL_ID/transcript \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Get a recording

<ParamField path="GET /api/v1/api/calls/{callId}/recording" type="calls:recording" required />

Returns the recording URL for the call.

<Note>
  `calls:transcript` and `calls:recording` are separate from `calls:read`. An integration can read call metadata without access to what was said.
</Note>

## Delete a call

<ParamField path="DELETE /api/v1/api/calls/{callId}" type="calls:delete" required />

<Warning>
  Deletion is permanent and removes the transcript and recording with the call record.
</Warning>

## Real-time instead of polling

Subscribe to `call.started`, `call.ended`, `call.transcript_ready`, and `call.human_escalation` rather than polling this endpoint. See [Webhooks](/api-reference/webhooks).