Usage & Billing

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.

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.

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 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

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

{
  "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

Example

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

{
  "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

Example

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

{
  "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 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.

Monitoring usage

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

# 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.