Get account usage

GET

https://api.getdial.ai/api/v1/usage

GET

/api/v1/usage

$ curl https://api.getdial.ai/api/v1/usage \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json"

1 {
2   "periodDays": 30,
3   "stats": {
4     "messages": {
5       "value": 1245,
6       "deltaPct": 5.3,
7       "spark": [
8         40,
9         38,
10         42,
11         45,
12         41,
13         39,
14         43,
15         44,
16         46,
17         48,
18         50,
19         52,
20         49,
21         47,
22         45,
23         44,
24         43,
25         42,
26         41,
27         40,
28         39,
29         38,
30         37,
31         36,
32         35,
33         34,
34         33,
35         32,
36         31,
37         30
38       ]
39     },
40     "calls": {
41       "value": 320,
42       "deltaPct": -2.1,
43       "spark": [
44         10,
45         11,
46         9,
47         12,
48         10,
49         11,
50         13,
51         14,
52         12,
53         11,
54         10,
55         9,
56         8,
57         7,
58         6,
59         7,
60         8,
61         9,
62         10,
63         11,
64         12,
65         13,
66         14,
67         15,
68         16,
69         17,
70         18,
71         19,
72         20,
73         21
74       ]
75     },
76     "minutes": {
77       "value": 1450,
78       "deltaPct": 3.7,
79       "spark": [
80         45,
81         48,
82         50,
83         52,
84         49,
85         47,
86         45,
87         44,
88         43,
89         42,
90         41,
91         40,
92         39,
93         38,
94         37,
95         36,
96         35,
97         34,
98         33,
99         32,
100         31,
101         30,
102         29,
103         28,
104         27,
105         26,
106         25,
107         24,
108         23,
109         22
110       ]
111     }
112   },
113   "series": [
114     {
115       "date": "2024-05-01",
116       "messages": 40,
117       "calls": 10
118     },
119     {
120       "date": "2024-05-02",
121       "messages": 38,
122       "calls": 11
123     },
124     {
125       "date": "2024-05-03",
126       "messages": 42,
127       "calls": 9
128     },
129     {
130       "date": "2024-05-04",
131       "messages": 45,
132       "calls": 12
133     },
134     {
135       "date": "2024-05-05",
136       "messages": 41,
137       "calls": 10
138     },
139     {
140       "date": "2024-05-06",
141       "messages": 39,
142       "calls": 11
143     },
144     {
145       "date": "2024-05-07",
146       "messages": 43,
147       "calls": 13
148     },
149     {
150       "date": "2024-05-08",
151       "messages": 44,
152       "calls": 14
153     },
154     {
155       "date": "2024-05-09",
156       "messages": 46,
157       "calls": 12
158     },
159     {
160       "date": "2024-05-10",
161       "messages": 48,
162       "calls": 11
163     },
164     {
165       "date": "2024-05-11",
166       "messages": 50,
167       "calls": 10
168     },
169     {
170       "date": "2024-05-12",
171       "messages": 52,
172       "calls": 9
173     },
174     {
175       "date": "2024-05-13",
176       "messages": 49,
177       "calls": 8
178     },
179     {
180       "date": "2024-05-14",
181       "messages": 47,
182       "calls": 7
183     },
184     {
185       "date": "2024-05-15",
186       "messages": 45,
187       "calls": 6
188     },
189     {
190       "date": "2024-05-16",
191       "messages": 44,
192       "calls": 7
193     },
194     {
195       "date": "2024-05-17",
196       "messages": 43,
197       "calls": 8
198     },
199     {
200       "date": "2024-05-18",
201       "messages": 42,
202       "calls": 9
203     },
204     {
205       "date": "2024-05-19",
206       "messages": 41,
207       "calls": 10
208     },
209     {
210       "date": "2024-05-20",
211       "messages": 40,
212       "calls": 11
213     },
214     {
215       "date": "2024-05-21",
216       "messages": 39,
217       "calls": 12
218     },
219     {
220       "date": "2024-05-22",
221       "messages": 38,
222       "calls": 13
223     },
224     {
225       "date": "2024-05-23",
226       "messages": 37,
227       "calls": 14
228     },
229     {
230       "date": "2024-05-24",
231       "messages": 36,
232       "calls": 15
233     },
234     {
235       "date": "2024-05-25",
236       "messages": 35,
237       "calls": 16
238     },
239     {
240       "date": "2024-05-26",
241       "messages": 34,
242       "calls": 17
243     },
244     {
245       "date": "2024-05-27",
246       "messages": 33,
247       "calls": 18
248     },
249     {
250       "date": "2024-05-28",
251       "messages": 32,
252       "calls": 19
253     },
254     {
255       "date": "2024-05-29",
256       "messages": 31,
257       "calls": 20
258     },
259     {
260       "date": "2024-05-30",
261       "messages": 30,
262       "calls": 21
263     }
264   ],
265   "callDuration": {
266     "sampleSize": 320,
267     "medianSec": 270,
268     "p95Sec": 900,
269     "longestSec": 1800,
270     "histogram": [
271       {
272         "label": "0–1m",
273         "count": 120,
274         "pct": 0.375
275       },
276       {
277         "label": "1–2m",
278         "count": 100,
279         "pct": 0.3125
280       },
281       {
282         "label": "2–5m",
283         "count": 70,
284         "pct": 0.21875
285       },
286       {
287         "label": "5–10m",
288         "count": 25,
289         "pct": 0.078125
290       },
291       {
292         "label": "10m+",
293         "count": 5,
294         "pct": 0.015625
295       }
296     ]
297   },
298   "topNumbers": [
299     {
300       "number": "+14155550142",
301       "nickname": "Support line",
302       "createdAt": "2023-11-10T14:20:00Z",
303       "count": 450
304     },
305     {
306       "number": "+14155550987",
307       "nickname": "Sales",
308       "createdAt": "2023-12-05T09:15:00Z",
309       "count": 320
310     },
311     {
312       "number": "+14155551234",
313       "nickname": null,
314       "createdAt": "2024-01-20T11:00:00Z",
315       "count": 210
316     }
317   ],
318   "breakdown": {
319     "messages": {
320       "d7": 300,
321       "d30": 1245,
322       "all": 15200
323     },
324     "calls": {
325       "d7": 75,
326       "d30": 320,
327       "all": 4200
328     },
329     "minutes": {
330       "d7": 350,
331       "d30": 1450,
332       "all": 19000
333     }
334   },
335   "totals": {
336     "messages": 15200,
337     "calls": 4200,
338     "numbers": 12
339   },
340   "currentPeriod": {
341     "start": "2024-04-15T00:00:00Z",
342     "end": "2024-05-15T00:00:00Z",
343     "daysTotal": 30,
344     "daysElapsed": 15,
345     "daysLeft": 15,
346     "all": {
347       "voice": {
348         "outbound": {
349           "domestic": {
350             "calls": 180,
351             "minutes": 900
352           },
353           "intl": {
354             "calls": 40,
355             "minutes": 200
356           }
357         },
358         "inbound": {
359           "domestic": {
360             "calls": 150,
361             "minutes": 750
362           },
363           "intl": {
364             "calls": 30,
365             "minutes": 150
366           }
367         }
368       },
369       "messages": {
370         "outbound": {
371           "domestic": {
372             "count": 600
373           },
374           "intl": {
375             "count": 120
376           }
377         },
378         "inbound": {
379           "domestic": {
380             "count": 550
381           },
382           "intl": {
383             "count": 100
384           }
385         }
386       }
387     },
388     "numbers": [
389       {
390         "id": "num_01a2b3c4d5e6f7g8h9i0",
391         "number": "+14155550142",
392         "nickname": "Support line",
393         "createdAt": "2023-11-10T14:20:00Z",
394         "breakdown": {
395           "voice": {
396             "outbound": {
397               "domestic": {
398                 "calls": 90,
399                 "minutes": 450
400               },
401               "intl": {
402                 "calls": 20,
403                 "minutes": 100
404               }
405             },
406             "inbound": {
407               "domestic": {
408                 "calls": 75,
409                 "minutes": 375
410               },
411               "intl": {
412                 "calls": 15,
413                 "minutes": 75
414               }
415             }
416           },
417           "messages": {
418             "outbound": {
419               "domestic": {
420                 "count": 300
421               },
422               "intl": {
423                 "count": 60
424               }
425             },
426             "inbound": {
427               "domestic": {
428                 "count": 275
429               },
430               "intl": {
431                 "count": 50
432               }
433             }
434           }
435         }
436       },
437       {
438         "id": "num_0a9b8c7d6e5f4g3h2i1j",
439         "number": "+14155550987",
440         "nickname": "Sales",
441         "createdAt": "2023-12-05T09:15:00Z",
442         "breakdown": {
443           "voice": {
444             "outbound": {
445               "domestic": {
446                 "calls": 60,
447                 "minutes": 300
448               },
449               "intl": {
450                 "calls": 10,
451                 "minutes": 50
452               }
453             },
454             "inbound": {
455               "domestic": {
456                 "calls": 50,
457                 "minutes": 250
458               },
459               "intl": {
460                 "calls": 10,
461                 "minutes": 50
462               }
463             }
464           },
465           "messages": {
466             "outbound": {
467               "domestic": {
468                 "count": 200
469               },
470               "intl": {
471                 "count": 40
472               }
473             },
474             "inbound": {
475               "domestic": {
476                 "count": 180
477               },
478               "intl": {
479                 "count": 30
480               }
481             }
482           }
483         }
484       }
485     ]
486   }
487 }

Activity analytics for the account over a selected window, derived from real message and call records: headline metrics with per-day spark series and deltas, a daily activity series, voice-call duration stats, the most active numbers, and fixed-window breakdown totals.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Query parameters

daysenumOptionalDefaults to 30

The analytics window. One of 7, 30, or 90. Defaults to 30; any other value falls back to 30.

Allowed values:

Response

Usage analytics for the selected window.

periodDaysinteger

The selected window in days (7, 30, or 90).

statsobject

Headline metrics for the selected window — each with a per-day spark series and percent change vs the previous equal window.

serieslist of objects

One entry per calendar day in the selected window (UTC), oldest first.

callDurationobject

Voice-call talk-time stats for connected calls (duration > 0) in the window.

topNumberslist of objects

Account numbers ranked by total activity (messages + calls) in the window, descending (up to 6).

breakdownobject

Fixed-window totals (last 7 days, last 30 days, all time).

totalsobject

All-time totals.

currentPeriodobject

Usage for the current period — a monthly cycle anchored to the account’s creation date (jumps of one month from createdAt; stands in until billing and pricing are defined). Independent of the days window. Split per number (plus an all aggregate) by direction and domestic/international.

Errors

401

Unauthorized Error