> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server.

# Usage & Billing

> Pay-as-you-go pricing, balance management, and usage monitoring

AgentPhone uses **pay-as-you-go billing**. Every account starts with a **\$5.00 free credit** — no credit card required. You pay only for what you use, and your balance is debited automatically as you make calls, send SMS, and maintain phone numbers.

## Pricing

| Resource              | Rate                                      |
| --------------------- | ----------------------------------------- |
| Phone numbers         | **\$3.00/month** per number               |
| Voice (webhook mode)  | **\$0.13/min** (per-second billing)       |
| Voice (hosted mode)   | **\$0.22/min** (per-second billing)       |
| SMS                   | **\$0.02/message** (inbound and outbound) |
| Call recording add-on | **\$5.00/month** (flat fee)               |

Voice calls are billed per second with a 1¢ minimum. Phone number fees are charged on provisioning and renew every 30 days.

## Call recording add-on

Call recording is an optional add-on at **\$5.00/month** (billed from your credit balance). When enabled, all voice calls are automatically recorded and the audio URL is included in call responses via the `recordingUrl` field.

Enable or disable recording from the **Billing** page in the dashboard. The fee is charged immediately on activation and renews every 30 days. If you cancel, recording stays active until the end of the current billing period. Existing recordings are preserved even after cancellation.

See [Calls > Call recording](/documentation/guides/calls#call-recording) for response field details.

## Balance & auto-recharge

Your project maintains a dollar balance. Usage is debited in real time. When your balance drops below a threshold you set, AgentPhone can automatically charge your card on file to top up.

Configure auto-recharge from the **Billing** page in the dashboard:

* **Threshold** — recharge when balance falls below this amount
* **Recharge amount** — how much to add each time

If auto-recharge is not enabled and your balance runs low, you'll receive an email notification. Phone numbers with unpaid renewals enter a **30-day grace period** before being released.

## Get usage

Retrieve current usage statistics for your project.

```
GET /v1/usage
```

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "numbers": {
    "used": 3,
    "limit": 10,
    "remaining": 7
  },
  "stats": {
    "totalMessages": 4500,
    "messagesLast24h": 120,
    "messagesLast7d": 850,
    "messagesLast30d": 3200,
    "totalCalls": 200,
    "callsLast24h": 8,
    "callsLast7d": 45,
    "callsLast30d": 160,
    "totalWebhookDeliveries": 4700,
    "successfulWebhookDeliveries": 4650,
    "failedWebhookDeliveries": 50
  },
  "periodStart": "2025-01-08T12:00:00Z",
  "periodEnd": "2025-01-15T12:00:00Z"
}
```

## Daily usage

Get a daily breakdown of usage for the last N days. Returns per-day counts of messages, calls, and webhook deliveries.

```
GET /v1/usage/daily
```

### Query parameters

| Parameter | Type    | Required | Default | Description                      |
| --------- | ------- | -------- | ------- | -------------------------------- |
| `days`    | integer | No       | 30      | Number of days to return (1-365) |

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/usage/daily?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "date": "2025-01-09",
      "messages": 12,
      "calls": 3,
      "webhooks": 15
    },
    {
      "date": "2025-01-10",
      "messages": 8,
      "calls": 5,
      "webhooks": 13
    }
  ],
  "days": 7
}
```

## Monthly usage

Get monthly usage aggregation for the last N months. Returns per-month totals of messages, calls, and webhook deliveries.

```
GET /v1/usage/monthly
```

### Query parameters

| Parameter | Type    | Required | Default | Description                       |
| --------- | ------- | -------- | ------- | --------------------------------- |
| `months`  | integer | No       | 6       | Number of months to return (1-24) |

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/usage/monthly?months=3" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "month": "2024-11",
      "messages": 342,
      "calls": 87,
      "webhooks": 429
    },
    {
      "month": "2024-12",
      "messages": 510,
      "calls": 124,
      "webhooks": 634
    }
  ],
  "months": 3
}
```

## Provisioning limits

Each account has a self-serve phone number limit. Check yours with `GET /v1/usage` (`numbers.limit` and `numbers.remaining`). Need more? [Contact us](https://calendar.app.google/kJQSTCyNYTphvCGm7) and we'll increase your limit.

To provision a number, your balance must be at least **\$3.00** (the first month's fee is charged immediately).

## Monitoring usage

Use the daily and monthly endpoints to track trends and manage spend:

```bash
# Check current usage
curl -s "https://api.agentphone.ai/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.numbers'

# Check daily trend for the last week
curl -s "https://api.agentphone.ai/v1/usage/daily?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data'
```

Set up auto-recharge to keep your account funded automatically, or monitor your balance and top up manually from the Billing page.