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

# Get account usage

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

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.


Reference: https://docs.getdial.ai/api-reference/rest-api/usage/get-usage

## Authentication

- `Authorization` header (bearer token, required) — Your Dial API key, sent as `Authorization: Bearer sk_live_...`

## Request

### Query parameters

- `days` (enum, optional, default: 30) — The analytics window. One of 7, 30, or 90. Defaults to 30; any other value falls back to 30.
  - Allowed values: `7`, `30`, `90`

## Response

### 200

Usage analytics for the selected window.

- `periodDays` (integer, optional) — The selected window in days (7, 30, or 90).
- `stats` (object, optional) — Headline metrics for the selected window — each with a per-day spark series and percent change vs the previous equal window.
  - `messages` (object, optional)
    - `value` (integer, optional) — Total for the selected window.
    - `deltaPct` (double, optional, nullable) — Percent change vs the previous equal window, or null when that window had no activity.
    - `spark` (list of integer, optional) — Per-day values across the selected window, oldest first.
  - `calls` (object, optional)
    - `value` (integer, optional) — Total for the selected window.
    - `deltaPct` (double, optional, nullable) — Percent change vs the previous equal window, or null when that window had no activity.
    - `spark` (list of integer, optional) — Per-day values across the selected window, oldest first.
  - `minutes` (object, optional)
    - `value` (integer, optional) — Total for the selected window.
    - `deltaPct` (double, optional, nullable) — Percent change vs the previous equal window, or null when that window had no activity.
    - `spark` (list of integer, optional) — Per-day values across the selected window, oldest first.
- `series` (list of object, optional) — One entry per calendar day in the selected window (UTC), oldest first.
  - `date` (date, optional)
  - `messages` (integer, optional)
  - `calls` (integer, optional)
- `callDuration` (object, optional) — Voice-call talk-time stats for connected calls (duration > 0) in the window.
  - `sampleSize` (integer, optional) — Number of connected calls in the window.
  - `medianSec` (integer, optional)
  - `p95Sec` (integer, optional)
  - `longestSec` (integer, optional)
  - `histogram` (list of object, optional) — Duration distribution across fixed buckets.
    - `label` (string, optional)
    - `count` (integer, optional)
    - `pct` (double, optional) — Fraction of the sample (0–1).
- `topNumbers` (list of object, optional) — Account numbers ranked by total activity (messages + calls) in the window, descending (up to 6).
  - `number` (string, optional)
  - `nickname` (string, optional, nullable) — User-set label for the number, or null. The dashboard falls back to the number's creation age when absent.
  - `createdAt` (datetime, optional)
  - `count` (integer, optional)
- `breakdown` (object, optional) — Fixed-window totals (last 7 days, last 30 days, all time).
  - `messages` (object, optional) — Totals for a metric over fixed windows.
    - `d7` (integer, optional) — Last 7 days.
    - `d30` (integer, optional) — Last 30 days.
    - `all` (integer, optional) — All time.
  - `calls` (object, optional) — Totals for a metric over fixed windows.
    - `d7` (integer, optional) — Last 7 days.
    - `d30` (integer, optional) — Last 30 days.
    - `all` (integer, optional) — All time.
  - `minutes` (object, optional) — Totals for a metric over fixed windows.
    - `d7` (integer, optional) — Last 7 days.
    - `d30` (integer, optional) — Last 30 days.
    - `all` (integer, optional) — All time.
- `totals` (object, optional) — All-time totals.
  - `messages` (integer, optional)
  - `calls` (integer, optional)
  - `numbers` (integer, optional)
- `currentPeriod` (object, optional) — 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.
  - `start` (datetime, optional) — Period start (inclusive).
  - `end` (datetime, optional) — Period end (exclusive); the period renews on this date.
  - `daysTotal` (integer, optional)
  - `daysElapsed` (integer, optional)
  - `daysLeft` (integer, optional)
  - `all` (object, optional) — Period usage split by direction (outbound/inbound) and geography (domestic/international).
    - `voice` (object, optional)
      - `outbound` (object, optional)
        - `domestic` (object, optional)
          - `calls` (integer, optional)
          - `minutes` (integer, optional)
        - `intl` (object, optional)
          - `calls` (integer, optional)
          - `minutes` (integer, optional)
      - `inbound` (object, optional)
        - `domestic` (object, optional)
          - `calls` (integer, optional)
          - `minutes` (integer, optional)
        - `intl` (object, optional)
          - `calls` (integer, optional)
          - `minutes` (integer, optional)
    - `messages` (object, optional)
      - `outbound` (object, optional)
        - `domestic` (object, optional)
          - `count` (integer, optional)
        - `intl` (object, optional)
          - `count` (integer, optional)
      - `inbound` (object, optional)
        - `domestic` (object, optional)
          - `count` (integer, optional)
        - `intl` (object, optional)
          - `count` (integer, optional)
  - `numbers` (list of object, optional) — Per-number breakdown, sorted by total period activity descending.
    - `id` (string, optional)
    - `number` (string, optional)
    - `nickname` (string, optional, nullable) — User-set label for the number, or null. The dashboard falls back to the number's creation age when absent.
    - `createdAt` (datetime, optional)
    - `breakdown` (object, optional) — Period usage split by direction (outbound/inbound) and geography (domestic/international).
      - `voice` (object, optional)
        - `outbound` (object, optional)
          - `domestic` (object, optional)
            - `calls` (integer, optional)
            - `minutes` (integer, optional)
          - `intl` (object, optional)
            - `calls` (integer, optional)
            - `minutes` (integer, optional)
        - `inbound` (object, optional)
          - `domestic` (object, optional)
            - `calls` (integer, optional)
            - `minutes` (integer, optional)
          - `intl` (object, optional)
            - `calls` (integer, optional)
            - `minutes` (integer, optional)
      - `messages` (object, optional)
        - `outbound` (object, optional)
          - `domestic` (object, optional)
            - `count` (integer, optional)
          - `intl` (object, optional)
            - `count` (integer, optional)
        - `inbound` (object, optional)
          - `domestic` (object, optional)
            - `count` (integer, optional)
          - `intl` (object, optional)
            - `count` (integer, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "periodDays": 30,
  "stats": {
    "messages": {
      "value": 1245,
      "deltaPct": 5.3,
      "spark": [
        40,
        38,
        42,
        45,
        41,
        39,
        43,
        44,
        46,
        48,
        50,
        52,
        49,
        47,
        45,
        44,
        43,
        42,
        41,
        40,
        39,
        38,
        37,
        36,
        35,
        34,
        33,
        32,
        31,
        30
      ]
    },
    "calls": {
      "value": 320,
      "deltaPct": -2.1,
      "spark": [
        10,
        11,
        9,
        12,
        10,
        11,
        13,
        14,
        12,
        11,
        10,
        9,
        8,
        7,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15,
        16,
        17,
        18,
        19,
        20,
        21
      ]
    },
    "minutes": {
      "value": 1450,
      "deltaPct": 3.7,
      "spark": [
        45,
        48,
        50,
        52,
        49,
        47,
        45,
        44,
        43,
        42,
        41,
        40,
        39,
        38,
        37,
        36,
        35,
        34,
        33,
        32,
        31,
        30,
        29,
        28,
        27,
        26,
        25,
        24,
        23,
        22
      ]
    }
  },
  "series": [
    {
      "date": "2024-05-01",
      "messages": 40,
      "calls": 10
    },
    {
      "date": "2024-05-02",
      "messages": 38,
      "calls": 11
    },
    {
      "date": "2024-05-03",
      "messages": 42,
      "calls": 9
    },
    {
      "date": "2024-05-04",
      "messages": 45,
      "calls": 12
    },
    {
      "date": "2024-05-05",
      "messages": 41,
      "calls": 10
    },
    {
      "date": "2024-05-06",
      "messages": 39,
      "calls": 11
    },
    {
      "date": "2024-05-07",
      "messages": 43,
      "calls": 13
    },
    {
      "date": "2024-05-08",
      "messages": 44,
      "calls": 14
    },
    {
      "date": "2024-05-09",
      "messages": 46,
      "calls": 12
    },
    {
      "date": "2024-05-10",
      "messages": 48,
      "calls": 11
    },
    {
      "date": "2024-05-11",
      "messages": 50,
      "calls": 10
    },
    {
      "date": "2024-05-12",
      "messages": 52,
      "calls": 9
    },
    {
      "date": "2024-05-13",
      "messages": 49,
      "calls": 8
    },
    {
      "date": "2024-05-14",
      "messages": 47,
      "calls": 7
    },
    {
      "date": "2024-05-15",
      "messages": 45,
      "calls": 6
    },
    {
      "date": "2024-05-16",
      "messages": 44,
      "calls": 7
    },
    {
      "date": "2024-05-17",
      "messages": 43,
      "calls": 8
    },
    {
      "date": "2024-05-18",
      "messages": 42,
      "calls": 9
    },
    {
      "date": "2024-05-19",
      "messages": 41,
      "calls": 10
    },
    {
      "date": "2024-05-20",
      "messages": 40,
      "calls": 11
    },
    {
      "date": "2024-05-21",
      "messages": 39,
      "calls": 12
    },
    {
      "date": "2024-05-22",
      "messages": 38,
      "calls": 13
    },
    {
      "date": "2024-05-23",
      "messages": 37,
      "calls": 14
    },
    {
      "date": "2024-05-24",
      "messages": 36,
      "calls": 15
    },
    {
      "date": "2024-05-25",
      "messages": 35,
      "calls": 16
    },
    {
      "date": "2024-05-26",
      "messages": 34,
      "calls": 17
    },
    {
      "date": "2024-05-27",
      "messages": 33,
      "calls": 18
    },
    {
      "date": "2024-05-28",
      "messages": 32,
      "calls": 19
    },
    {
      "date": "2024-05-29",
      "messages": 31,
      "calls": 20
    },
    {
      "date": "2024-05-30",
      "messages": 30,
      "calls": 21
    }
  ],
  "callDuration": {
    "sampleSize": 320,
    "medianSec": 270,
    "p95Sec": 900,
    "longestSec": 1800,
    "histogram": [
      {
        "label": "0–1m",
        "count": 120,
        "pct": 0.375
      },
      {
        "label": "1–2m",
        "count": 100,
        "pct": 0.3125
      },
      {
        "label": "2–5m",
        "count": 70,
        "pct": 0.21875
      },
      {
        "label": "5–10m",
        "count": 25,
        "pct": 0.078125
      },
      {
        "label": "10m+",
        "count": 5,
        "pct": 0.015625
      }
    ]
  },
  "topNumbers": [
    {
      "number": "+14155550142",
      "nickname": "Support line",
      "createdAt": "2023-11-10T14:20:00Z",
      "count": 450
    },
    {
      "number": "+14155550987",
      "nickname": "Sales",
      "createdAt": "2023-12-05T09:15:00Z",
      "count": 320
    },
    {
      "number": "+14155551234",
      "nickname": null,
      "createdAt": "2024-01-20T11:00:00Z",
      "count": 210
    }
  ],
  "breakdown": {
    "messages": {
      "d7": 300,
      "d30": 1245,
      "all": 15200
    },
    "calls": {
      "d7": 75,
      "d30": 320,
      "all": 4200
    },
    "minutes": {
      "d7": 350,
      "d30": 1450,
      "all": 19000
    }
  },
  "totals": {
    "messages": 15200,
    "calls": 4200,
    "numbers": 12
  },
  "currentPeriod": {
    "start": "2024-04-15T00:00:00Z",
    "end": "2024-05-15T00:00:00Z",
    "daysTotal": 30,
    "daysElapsed": 15,
    "daysLeft": 15,
    "all": {
      "voice": {
        "outbound": {
          "domestic": {
            "calls": 180,
            "minutes": 900
          },
          "intl": {
            "calls": 40,
            "minutes": 200
          }
        },
        "inbound": {
          "domestic": {
            "calls": 150,
            "minutes": 750
          },
          "intl": {
            "calls": 30,
            "minutes": 150
          }
        }
      },
      "messages": {
        "outbound": {
          "domestic": {
            "count": 600
          },
          "intl": {
            "count": 120
          }
        },
        "inbound": {
          "domestic": {
            "count": 550
          },
          "intl": {
            "count": 100
          }
        }
      }
    },
    "numbers": [
      {
        "id": "num_01a2b3c4d5e6f7g8h9i0",
        "number": "+14155550142",
        "nickname": "Support line",
        "createdAt": "2023-11-10T14:20:00Z",
        "breakdown": {
          "voice": {
            "outbound": {
              "domestic": {
                "calls": 90,
                "minutes": 450
              },
              "intl": {
                "calls": 20,
                "minutes": 100
              }
            },
            "inbound": {
              "domestic": {
                "calls": 75,
                "minutes": 375
              },
              "intl": {
                "calls": 15,
                "minutes": 75
              }
            }
          },
          "messages": {
            "outbound": {
              "domestic": {
                "count": 300
              },
              "intl": {
                "count": 60
              }
            },
            "inbound": {
              "domestic": {
                "count": 275
              },
              "intl": {
                "count": 50
              }
            }
          }
        }
      },
      {
        "id": "num_0a9b8c7d6e5f4g3h2i1j",
        "number": "+14155550987",
        "nickname": "Sales",
        "createdAt": "2023-12-05T09:15:00Z",
        "breakdown": {
          "voice": {
            "outbound": {
              "domestic": {
                "calls": 60,
                "minutes": 300
              },
              "intl": {
                "calls": 10,
                "minutes": 50
              }
            },
            "inbound": {
              "domestic": {
                "calls": 50,
                "minutes": 250
              },
              "intl": {
                "calls": 10,
                "minutes": 50
              }
            }
          },
          "messages": {
            "outbound": {
              "domestic": {
                "count": 200
              },
              "intl": {
                "count": 40
              }
            },
            "inbound": {
              "domestic": {
                "count": 180
              },
              "intl": {
                "count": 30
              }
            }
          }
        }
      }
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.getdial.ai/api/v1/usage"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getdial.ai/api/v1/usage';
const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdial.ai/api/v1/usage"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getdial.ai/api/v1/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.getdial.ai/api/v1/usage")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.getdial.ai/api/v1/usage', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getdial.ai/api/v1/usage");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getdial.ai/api/v1/usage")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```