Usage

The Usage endpoints provide information about your project’s current resource consumption, plan limits, and historical usage trends.

Get usage

Retrieve current usage statistics and limits for your project.

GET /v1/usage

Example

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

1
{
2
  "plan": {
3
    "name": "pro",
4
    "limits": {
5
      "numbers": 10,
6
      "messagesPerMonth": 10000,
7
      "voiceMinutesPerMonth": 500,
8
      "maxCallDurationMinutes": 30,
9
      "concurrentCalls": 5
10
    }
11
  },
12
  "numbers": {
13
    "used": 3,
14
    "limit": 10,
15
    "remaining": 7
16
  },
17
  "stats": {
18
    "totalMessages": 4500,
19
    "messagesLast24h": 120,
20
    "messagesLast7d": 850,
21
    "messagesLast30d": 3200,
22
    "totalCalls": 200,
23
    "callsLast24h": 8,
24
    "callsLast7d": 45,
25
    "callsLast30d": 160,
26
    "totalWebhookDeliveries": 4700,
27
    "successfulWebhookDeliveries": 4650,
28
    "failedWebhookDeliveries": 50
29
  },
30
  "periodStart": "2025-01-01T00:00:00Z",
31
  "periodEnd": "2025-01-08T00:00:00Z"
32
}

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.to/v1/usage/daily?days=7" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "date": "2025-01-09",
5
      "messages": 12,
6
      "calls": 3,
7
      "webhooks": 15
8
    },
9
    {
10
      "date": "2025-01-10",
11
      "messages": 8,
12
      "calls": 5,
13
      "webhooks": 13
14
    }
15
  ],
16
  "days": 7
17
}

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.to/v1/usage/monthly?months=3" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "month": "2024-11",
5
      "messages": 342,
6
      "calls": 87,
7
      "webhooks": 429
8
    },
9
    {
10
      "month": "2024-12",
11
      "messages": 510,
12
      "calls": 124,
13
      "webhooks": 634
14
    }
15
  ],
16
  "months": 3
17
}

Understanding limits

Phone numbers

The phone numbers limit is a lifetime limit — it counts all numbers ever provisioned (including released ones).

Messages

The messages per month limit resets at the start of each billing period. Both inbound and outbound messages count toward this limit.

Voice minutes

The voice minutes per month limit resets monthly. Both inbound and outbound call minutes are counted.

Call duration

The max call duration is a hard limit on individual call length. Calls that reach this duration are automatically terminated.

Concurrent calls

The concurrent calls limit controls how many voice calls can be active simultaneously across all your agent’s phone numbers.

Plan comparison

Monitoring usage

Use the daily and monthly endpoints to track trends and avoid hitting limits:

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

When your usage approaches a limit, consider upgrading your plan or implementing rate limiting in your application.