> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://agentphone.to/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentphone.to/docs/_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 These are standard rates; account-specific pricing and destination/carrier charges can differ. Confirm the price shown in your account before purchasing or sending traffic. | Resource | Standard rate and billing unit | | --------------------------------------- | -------------------------------------------------------- | | US/Canada standard number | **\$3.00 every 30 days** per number, paid from credits | | UK standard number, on enabled accounts | **\$6.00 every 30 days**, SMS-only | | iMessage inbound line | **\$150/month**, card subscription | | iMessage outbound line | **\$250/month**, card subscription | | Custom iMessage area code | **\$75 one-time setup**, in addition to the subscription | | Voice in webhook mode | **\$0.13/min**, billed per second | | Voice in hosted mode | **\$0.22/min**, billed per second | | US/Canada SMS | **\$0.02/segment**, inbound and outbound | | MMS | **\$0.03/message** | | RCS text | **\$0.013 per 160-byte UTF-8 segment** | | RCS rich media | **\$0.031/message** | | Number lookup | **\$0.009/number** | | Call recording add-on | **\$5.00 every 30 days**, paid from credits | Voice has a 1¢ minimum charge per call. SMS destination pricing can differ: the standard UK outbound SMS rate is \$0.07/segment. iMessage messaging is covered by its line subscription; associated voice usage is billed separately. WhatsApp charges are billed directly by Meta; see the [WhatsApp guide](/docs/documentation/guides/whatsapp#billing). ### SMS segments A message and a billable segment are different units: * GSM-7: up to 160 septets for one segment; 153 per part for a longer message. Some characters use two septets. * Unicode: up to 70 UTF-16 code units for one segment; 67 per part for a longer message. Emoji can use two units. * For example, 161 ordinary GSM-7 letters use two segments. Adding Unicode characters can change the encoding and increase the segment count. Usage counts are not a dollar invoice: one message can incur multiple segments, and different channels have different billing units. ## 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](/docs/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. Credit-billed phone numbers with unpaid renewals enter a **30-day grace period** before release. iMessage line subscriptions are charged to your card separately; increasing your credit balance does not pay that subscription. ### Auto-recharge is enabled but not topping up Auto-recharge can pause after five failed payment attempts or a hard card decline. Check Billing for a paused state and the payment failure. Update or re-add a working payment method to clear the pause; simply leaving the toggle enabled does not fix a declined card. Add funds manually if you need to restore service immediately. ### Receipts Open **Billing** and look for the receipt link on the payment transaction. If a receipt is missing, contact support with the payment date and transaction reference. Do not send card details or API keys. ## Get usage Retrieve current usage statistics for your project or the selected sub-account. This endpoint returns counts and provisioning limits, not a `plan` object, credit balance, or itemized bill. Check Billing for balance and payment history. ``` 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. Standard number provisioning requires enough credits for that number’s first billing period. iMessage provisioning requires a payment method and a separate subscription; see [iMessage](/docs/imessage). ## 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. ## Failed messages and refunds An accepted message can fail later. Eligible non-billable SMS/MMS failures and some RCS failures are automatically credited after the failure is recorded and reconciled. Eligibility depends on transport and the failure code; a `failed` status alone does not guarantee a refund. Check Billing for the original charge and any refund transaction, and contact support with the message ID if the result is unclear.